Flow Client Library (FCL) API Reference
For release updates, see the repo
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.
_13import * as fcl from '@onflow/fcl';_13_13fcl_13 .config() // returns the config instance_13 .put('foo', 'bar') // configures "foo" to be "bar"_13 .put('baz', 'buz'); // configures "baz" to be "buz"_13_13// OR_13_13fcl.config({_13 foo: 'bar',_13 baz: 'buz',_13});
Getting Configuration Valuesβ
The config
instance has an asynchronous get
method. You can also pass it a fallback value.
_15import * as fcl from '@onflow/fcl';_15_15fcl.config().put('foo', 'bar').put('woot', 5).put('rawr', 7);_15_15const FALLBACK = 1;_15_15async function addStuff() {_15 var woot = await fcl.config().get('woot', FALLBACK); // will be 5 -- set in the config before_15 var rawr = await fcl.config().get('rawr', FALLBACK); // will be 7 -- set in the config before_15 var hmmm = await fcl.config().get('hmmm', FALLBACK); // will be 1 -- uses fallback because this isnt in the config_15_15 return woot + rawr + hmmm;_15}_15_15addStuff().then((d) => console.log(d)); // 13 (5 + 7 + 1)
Common Configuration Keysβ
Name | Example | Description |
---|---|---|
accessNode.api (required) | https://rest-testnet.onflow.org | API URL for the Flow Blockchain Access Node you want to be communicating with. See all available access node endpoints here. |
app.detail.title | Cryptokitties | Your applications title, can be requested by wallets and other services. |
app.detail.icon | https://fcl-discovery.onflow.org/images/blocto.png | Url for your applications icon, can be requested by wallets and other services. |
challenge.handshake | DEPRECATED | Use discovery.wallet instead. |
discovery.authn.endpoint | https://fcl-discovery.onflow.org/api/testnet/authn | Endpoint for alternative configurable Wallet Discovery mechanism. Read more on discovery |
discovery.wallet (required) | https://fcl-discovery.onflow.org/testnet/authn | Points FCL at the Wallet or Wallet Discovery mechanism. |
discovery.wallet.method | IFRAME/RPC , POP/RPC , TAB/RPC , HTTP/POST , or EXT/RPC | Describes which service strategy a wallet should use. |
fcl.limit | 100 | Specifies fallback compute limit if not provided in transaction. Provided as integer. |
flow.network (recommended) | testnet | Used in conjunction with stored interactions and provides FCLCryptoContract address for testnet and mainnet . Possible values: local , testnet , mainnet . |
Using Contracts in Scripts and Transactionsβ
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.
_27import * as fcl from '@onflow/fcl';_27_27fcl.config().put('0xFungibleToken', '0xf233dcee88fe0abe');_27_27async function myScript() {_27 return fcl_27 .send([_27 fcl.script`_27 import FungibleToken from 0xFungibleToken // will be replaced with 0xf233dcee88fe0abe because of the configuration_27_27 pub fun main() { /* Rest of the script goes here */ }_27 `,_27 ])_27 .then(fcl.decode);_27}_27_27async function myTransaction() {_27 return fcl_27 .send([_27 fcl.transaction`_27 import FungibleToken from 0xFungibleToken // will be replaced with 0xf233dcee88fe0abe because of the configuration_27_27 transaction { /* Rest of the transaction goes here */ }_27 `,_27 ])_27 .then(fcl.decode);_27}
Exampleβ
_11import * as fcl from '@onflow/fcl';_11_11fcl_11 .config()_11 .put('flow.network', 'testnet')_11 .put('accessNode.api', 'https://rest-testnet.onflow.org')_11 .put('discovery.wallet', 'https://fcl-discovery.onflow.org/testnet/authn')_11 .put('app.detail.title', 'Test Harness')_11 .put('app.detail.icon', 'https://i.imgur.com/r23Zhvu.png')_11 .put('service.OpenID.scopes', 'email email_verified name zoneinfo')_11 .put('0xFlowToken', '0x7e60df042a9c0868');
Using 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.
_10import { config } from '@onflow/fcl';_10import flowJSON from '../flow.json';_10_10config({_10 'flow.network': 'testnet',_10 'accessNode.api': 'https://rest-testnet.onflow.org',_10 'discovery.wallet': `https://fcl-discovery.onflow.org/testnet/authn`,_10}).load({ flowJSON });
Let's say your flow.json
file looks like this:
_10{_10 "contracts": {_10 "HelloWorld": "cadence/contracts/HelloWorld.cdc"_10 }_10}
Then in your scripts and transactions, all you have to do is:
_10import "HelloWorld"
FCL will automatically replace the contract name with the address for the network you are using.
Note: never put private keys in your
flow.json
. You should use the key/location syntax to separate your keys into a separate git ignored file.
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.
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β
_10import * as fcl from '@onflow/fcl';_10fcl_10 .config()_10 .put('accessNode.api', 'https://rest-testnet.onflow.org')_10 .put('discovery.wallet', 'https://fcl-discovery.onflow.org/testnet/authn');_10// anywhere on the page_10fcl.authenticate();
Noteβ
β οΈ authenticate
can also take a service returned from discovery with fcl.authenticate({ service })
.
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β
_10import * as fcl from '@onflow/fcl';_10fcl.config().put('accessNode.api', 'https://rest-testnet.onflow.org');_10// first authenticate to set current user_10fcl.authenticate();_10// ... somewhere else & sometime later_10fcl.unauthenticate();_10// fcl.currentUser.loggedIn === null
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β
_10import * as fcl from '@onflow/fcl';_10// first authenticate to set current user_10fcl.authenticate();_10// ... somewhere else & sometime later_10fcl.reauthenticate();_10// logs out user and opens up login/sign-up flow
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β
Type | Description |
---|---|
AuthorizationObject | An object containing the necessary details from the current user to authorize a transaction in any role. |
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.
_22import * as fcl from '@onflow/fcl';_22// login somewhere before_22fcl.authenticate();_22// once logged in authz will produce values_22console.log(fcl.authz);_22// prints {addr, signingFunction, keyId, sequenceNum} from the current authenticated user._22_22const txId = await fcl.mutate({_22 cadence: `_22 import Profile from 0xba1132bc08f82fe2_22 _22 transaction(name: String) {_22 prepare(account: AuthAccount) {_22 account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)_22 }_22 }_22 `,_22 args: (arg, t) => [arg('myName', t.String)],_22 proposer: fcl.authz, // optional - default is fcl.authz_22 payer: fcl.authz, // optional - default is fcl.authz_22 authorizations: [fcl.authz], // optional - default is [fcl.authz]_22});
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.
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β
Name | Type | |
---|---|---|
callback | function | The callback will be called with the current user as the first argument when the current user is set or removed. |
Usageβ
_24import React, { useState, useEffect } from 'react';_24import * as fcl from '@onflow/fcl';_24_24export function AuthCluster() {_24 const [user, setUser] = useState({ loggedIn: null });_24 useEffect(() => fcl.currentUser.subscribe(setUser), []); // sets the callback for FCL to use_24_24 if (user.loggedIn) {_24 return (_24 <div>_24 <span>{user?.addr ?? 'No Address'}</span>_24 <button onClick={fcl.unauthenticate}>Log Out</button> {/* once logged out in setUser(user) will be called */}_24 </div>_24 );_24 } else {_24 return (_24 <div>_24 <button onClick={fcl.logIn}>Log In</button>{' '}_24 {/* once logged in setUser(user) will be called */}_24 <button onClick={fcl.signUp}>Sign Up</button> {/* once signed up, setUser(user) will be called */}_24 </div>_24 );_24 }_24}
currentUser.snapshot
β
Returns the current user object. This is the same object that is set and available on fcl.currentUser.subscribe(callback)
.
Usageβ
_10// returns the current user object_10const user = fcl.currentUser.snapshot();_10_10// subscribes to the current user object and logs to console on changes_10fcl.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β
Name | Type | Description |
---|---|---|
message | string (required) | A hexadecimal string to be signed |
Returnsβ
Type | Description |
---|---|
Array | An Array of CompositeSignatures: signature |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10export const signMessage = async () => {_10 const MSG = Buffer.from('FOO').toString('hex');_10 try {_10 return await currentUser.signUserMessage(MSG);_10 } catch (error) {_10 console.log(error);_10 }_10};
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β
Environment | Example |
---|---|
Mainnet | https://fcl-discovery.onflow.org/api/authn |
Testnet | https://fcl-discovery.onflow.org/api/testnet/authn |
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β
_24import './config';_24import { useState, useEffect } from 'react';_24import * as fcl from '@onflow/fcl';_24_24function Component() {_24 const [wallets, setWallets] = useState([]);_24 useEffect(_24 () => fcl.discovery.authn.subscribe((res) => setWallets(res.results)),_24 [],_24 );_24_24 return (_24 <div>_24 {wallets.map((wallet) => (_24 <button_24 key={wallet.provider.address}_24 onClick={() => fcl.authenticate({ service: wallet })}_24 >_24 Login with {wallet.provider.name}_24 </button>_24 ))}_24 </div>_24 );_24}
authnβ
More Configurationβ
By default, limited functionality services or services that require developer registration, like Ledger or Dapper Wallet, require apps to opt-in in order to display to users. To enable opt-in 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.
_10import { config } from '@onflow/fcl';_10_10config({_10 'discovery.authn.endpoint':_10 'https://fcl-discovery.onflow.org/api/testnet/authn', // Endpoint set to Testnet_10 'discovery.authn.include': ['0x9d2e44203cb13051'], // Ledger wallet address on Testnet set to be included_10});
Opt-In Wallet Addresses on Testnet and Mainnet
Service | Testnet | Mainnet |
---|---|---|
Dapper Wallet | 0x82ec283f88a62e65 | 0xead892083b3e2c6c |
Ledger | 0x9d2e44203cb13051 | 0xe5cd26afebe62781 |
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.
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.
Key | Type | Description |
---|---|---|
cadence | string (required) | A valid cadence script. |
args | ArgumentFunction | Any arguments to the script if needed should be supplied via a function that returns an array of arguments. |
limit | number | Compute (Gas) limit for query. Read the documentation about computation cost for information about how computation cost is calculated on Flow. |
Returnsβ
Type | Description |
---|---|
any | A JSON representation of the response. |
Usageβ
_16import * as fcl from '@onflow/fcl';_16_16const result = await fcl.query({_16 cadence: `_16 pub fun main(a: Int, b: Int, addr: Address): Int {_16 log(addr)_16 return a + b_16 }_16 `,_16 args: (arg, t) => [_16 arg(7, t.Int), // a: Int_16 arg(6, t.Int), // b: Int_16 arg('0xba1132bc08f82fe2', t.Address), // addr: Address_16 ],_16});_16console.log(result); // 13
Examplesβ
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.
Key | Type | Description |
---|---|---|
cadence | string (required) | A valid cadence transaction. |
args | ArgumentFunction | Any arguments to the script if needed should be supplied via a function that returns an array of arguments. |
limit | number | Compute (Gas) limit for query. Read the documentation about computation cost for information about how computation cost is calculated on Flow. |
proposer | AuthorizationFunction | The authorization function that returns a valid AuthorizationObject for the proposer role. |
Returnsβ
Type | Description |
---|---|
string | The transaction ID. |
Usageβ
_16import * as fcl from '@onflow/fcl';_16// login somewhere before_16fcl.authenticate();_16_16const txId = await fcl.mutate({_16 cadence: `_16 import Profile from 0xba1132bc08f82fe2_16 _16 transaction(name: String) {_16 prepare(account: AuthAccount) {_16 account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)_16 }_16 }_16 `,_16 args: (arg, t) => [arg('myName', t.String)],_16});
Examplesβ
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β
Name | Type | Description |
---|---|---|
message | string (required) | A hexadecimal string |
compositeSignatures | Array (required) | An Array of CompositeSignatures |
opts | Object (optional) | opts.fclCryptoContract can be provided to override FCLCryptoContract address for local development |
Returnsβ
Type | Description |
---|---|
Boolean | true if verified or false |
Usageβ
_15import * as fcl from '@onflow/fcl';_15_15const isValid = await fcl.AppUtils.verifyUserSignatures(_15 Buffer.from('FOO').toString('hex'),_15 [_15 {_15 f_type: 'CompositeSignature',_15 f_vsn: '1.0.0',_15 addr: '0x123',_15 keyId: 0,_15 signature: 'abc123',_15 },_15 ],_15 { fclCryptoContract },_15);
Examplesβ
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β
Name | Type | Description |
---|---|---|
appIdentifier | string (required) | A hexadecimal string |
accountProofData | Object (required) | Object with properties: address : string - A Flow account address. nonce : string - A random string in hexadecimal format (minimum 32 bytes in total, i.e 64 hex characters) signatures : Object[] - An array of composite signatures to verify |
opts | Object (optional) | opts.fclCryptoContract can be provided to overide FCLCryptoContract address for local development |
Returnsβ
Type | Description |
---|---|
Boolean | true if verified or false |
Usageβ
_13import * as fcl from "@onflow/fcl"_13_13const accountProofData = {_13 address: "0x123",_13 nonce: "F0123"_13 signatures: [{f_type: "CompositeSignature", f_vsn: "1.0.0", addr: "0x123", keyId: 0, signature: "abc123"}],_13}_13_13const isValid = await fcl.AppUtils.verifyAccountProof(_13 "AwesomeAppId",_13 accountProofData,_13 {fclCryptoContract}_13)
Examplesβ
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}
orfcl.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β
Name | Type | Description |
---|---|---|
builders | [Builders] | See builder functions. |
Returnsβ
Type | Description |
---|---|
ResponseObject | An object containing the data returned from the chain. Should always be decoded with fcl.decode() to get back appropriate JSON keys and values. |
Usageβ
_18import * as fcl from '@onflow/fcl';_18_18// a script only needs to resolve the arguments to the script_18const response = await fcl.send([fcl.script`${script}`, fcl.args(args)]);_18// note: response values are encoded, call await fcl.decode(response) to get JSON_18_18// a transaction requires multiple 'builders' that need to be resolved prior to being sent to the chain - such as setting the authorizations._18const response = await fcl.send([_18 fcl.transaction`_18 ${transaction}_18 `,_18 fcl.args(args),_18 fcl.proposer(proposer),_18 fcl.authorizations(authorizations),_18 fcl.payer(payer),_18 fcl.limit(9999),_18]);_18// note: response contains several values (Cad)
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β
Name | Type | Description |
---|---|---|
response | ResponseObject | Should be the response returned from fcl.send([...]) |
Returnsβ
Type | Description |
---|---|
any | A JSON representation of the raw string response depending on the cadence code executed. The return value can be a single value and type or an object with multiple types. |
Usageβ
_16import * as fcl from '@onflow/fcl';_16_16// simple script to add 2 numbers_16const response = await fcl.send([_16 fcl.script`_16 pub fun main(int1: Int, int2: Int): Int {_16 return int1 + int2_16 }_16 `,_16 fcl.args([fcl.arg(1, fcl.t.Int), fcl.arg(2, fcl.t.Int)]),_16]);_16_16const decoded = await fcl.decode(response);_16_16assert(3 === decoded);_16assert(typeof decoded === 'number');
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β
Name | Type | Description |
---|---|---|
address | Address | Address of the user account with or without a prefix (both formats are supported). |
Returns after decodingβ
Type | Description |
---|---|
AccountObject | A JSON representation of a user account. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10// somewhere in an async function_10// fcl.account is the same as this function_10const getAccount = async (address) => {_10 const account = await fcl.send([fcl.getAccount(address)]).then(fcl.decode);_10 return account;_10};
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.getblock(isSealed)
if you do not need to pair with any other builders.
Argumentsβ
Name | Type | Default | Description |
---|---|---|---|
isSealed | boolean | false | If the latest block should be sealed or not. See block states. |
Returns after decodingβ
Type | Description |
---|---|
BlockObject | The latest block if not used with any other builders. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const latestSealedBlock = await fcl_10 .send([_10 fcl.getBlock(true), // isSealed = true_10 ])_10 .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β
Name | Type | Description |
---|---|---|
blockHeight | number | The height of the block to execute the interaction at. |
Returnsβ
Type | Description |
---|---|
Partial Interaction | A partial interaction to be paired with another interaction such as fcl.getBlock() or fcl.getAccount() . |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10await 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β
Name | Type | Description |
---|---|---|
blockId | string | The ID of the block to execute the interaction at. |
Returnsβ
Type | Description |
---|---|
Partial Interaction | A partial interaction to be paired with another interaction such as fcl.getBlock() or fcl.getAccount() . |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10await 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β
Type | Description |
---|---|
BlockHeaderObject | The latest block header if not used with any other builders. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const latestBlockHeader = await fcl_10 .send([fcl.getBlockHeader()])_10 .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β
Name | Type | Description |
---|---|---|
eventName | EventName | The name of the event. |
fromBlockHeight | number | The height of the block to start looking for events (inclusive). |
toBlockHeight | number | The height of the block to stop looking for events (inclusive). |
Returns after decodingβ
Type | Description |
---|---|
[EventObject] | An array of events that matched the eventName. |
Usageβ
_11import * as fcl from '@onflow/fcl';_11_11const events = await fcl_11 .send([_11 fcl.getEventsAtBlockHeightRange(_11 'A.7e60df042a9c0868.FlowToken.TokensWithdrawn',_11 35580624,_11 35580624,_11 ),_11 ])_11 .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β
Name | Type | Description |
---|---|---|
eventName | EventName | The name of the event. |
blockIds | number | The ids of the blocks to scan for events. |
Returns after decodingβ
Type | Description |
---|---|
[EventObject] | An array of events that matched the eventName. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const events = await fcl_10 .send([_10 fcl.getEventsAtBlockIds('A.7e60df042a9c0868.FlowToken.TokensWithdrawn', [_10 'c4f239d49e96d1e5fbcf1f31027a6e582e8c03fcd9954177b7723fdb03d938c7',_10 '5dbaa85922eb194a3dc463c946cc01c866f2ff2b88f3e59e21c0d8d00113273f',_10 ]),_10 ])_10 .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β
Name | Type | Description |
---|---|---|
collectionID | string | The id of the collection. |
Returns after decodingβ
Type | Description |
---|---|
CollectionObject | An object with the id and a list of transactions within the requested collection. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const collection = await fcl_10 .send([_10 fcl.getCollection(_10 'cccdb0c67d015dc7f6444e8f62a3244ed650215ed66b90603006c70c5ef1f6e5',_10 ),_10 ])_10 .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β
Name | Type | Description |
---|---|---|
transactionId | string | The transactionID returned when submitting a transaction. Example: 9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3 |
Returns after decodingβ
Returnsβ
Type | Description |
---|---|
TransactionStatusObject | Object representing the result/status of a transaction |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const status = await fcl_10 .send([_10 fcl.getTransactionStatus(_10 '9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3',_10 ),_10 ])_10 .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β
Name | Type | Description |
---|---|---|
transactionId | string | The transactionID returned when submitting a transaction. Example: 9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3 |
Returns after decodingβ
Returnsβ
Type | Description |
---|---|
TransactionObject | An full transaction object containing a payload and signatures |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const tx = await fcl_10 .send([_10 fcl.getTransaction(_10 '9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3',_10 ),_10 ])_10 .then(fcl.decode);
subscribeEvents
β
The subscribeEvents
feature is only available in the latest alpha release of FCL. To use it, install @onflow/fcl@alpha
.
A build that returns a event stream connection once decoded. It will establish a WebSocket connection to the Access Node and subscribe to events with the given parameters.
Argumentsβ
Name | Type | Description |
---|---|---|
opts | Object | An object with the following keys: |
opts.startBlockId | string | undefined | The block ID to start listening for events. Example: 9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3 |
opts.startHeight | number | undefined | The block height to start listening for events. Example: 123 |
opts.eventTypes | string[] | undefined | The event types to listen for. Example: A.7e60df042a9c0868.FlowToken.TokensWithdrawn |
opts.addresses | string[] | undefined | The addresses to listen for. Example: 0x7e60df042a9c0868 |
opts.contracts | string[] | undefined | The contracts to listen for. Example: 0x7e60df042a9c0868 |
opts.heartbeatInterval | number | undefined | The interval in milliseconds to send a heartbeat to the Access Node. Example: 10000 |
Returns after decodingβ
Returnsβ
Type | Description |
---|---|
EventStreamConnection | A connection to the event stream |
Usageβ
_27import * as fcl from '@onflow/fcl';_27_27const eventStream = await fcl_27 .send([_27 fcl.subscribeEvents({_27 eventTypes: 'A.7e60df042a9c0868.FlowToken.TokensWithdrawn',_27 }),_27 ])_27 .then(fcl.decode);_27_27eventStream.on('heartbeat', (heartbeat) => {_27 console.log(heartbeat);_27});_27_27eventStream.on('events', (event) => {_27 console.log(event);_27});_27_27eventStream.on('error', (error) => {_27 console.log(error);_27});_27_27eventStream.on('end', () => {_27 console.log('Connection closed');_27});_27_27eventStream.close();
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}
orfcl.mutate({...options})
arg
β
A utility builder to be used with fcl.args[...]
to create FCL supported arguments for interactions.
Argumentsβ
Name | Type | Description |
---|---|---|
value | any | Any value that you are looking to pass to other builders. |
type | FType | A type supported by Flow. |
Returnsβ
Type | Description |
---|---|
ArgumentObject | Holds the value and type passed in. |
Usageβ
_15import * as fcl from '@onflow/fcl';_15_15await fcl_15 .send([_15 fcl.script`_15 pub fun main(a: Int, b: Int): Int {_15 return a + b_15 }_15 `,_15 fcl.args([_15 fcl.arg(5, fcl.t.Int), // a_15 fcl.arg(4, fcl.t.Int), // b_15 ]),_15 ])_15 .then(fcl.decode);
args
β
A utility builder to be used with other builders to pass in arguments with a value and supported type.
Argumentsβ
Name | Type | Description |
---|---|---|
args | [Argument Objects] | An array of arguments that you are looking to pass to other builders. |
Returnsβ
Type | Description |
---|---|
Partial Interaction | An interaction that contains the arguments and types passed in. This alone is a partial and incomplete interaction. |
Usageβ
_15import * as fcl from '@onflow/fcl';_15_15await fcl_15 .send([_15 fcl.script`_15 pub fun main(a: Int, b: Int): Int {_15 return a + b_15 }_15 `,_15 fcl.args([_15 fcl.arg(5, fcl.t.Int), // a_15 fcl.arg(4, fcl.t.Int), // b_15 ]),_15 ])_15 .then(fcl.decode); // 9
Template Buildersβ
β οΈRecommended: The following functionality is simplified by
fcl.query({...options}
orfcl.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β
Name | Type | Description |
---|---|---|
CODE | string | Should be valid Cadence script. |
Returnsβ
Type | Description |
---|---|
Interaction | An interaction containing the code passed in. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const code = `_10 pub fun main(): Int {_10 return 5 + 4_10 }_10`;_10const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);_10console.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β
Name | Type | Description |
---|---|---|
CODE | string | Should be valid a Cadence transaction. |
Returnsβ
Type | Description |
---|---|
Partial Interaction | An partial interaction containing the code passed in. Further builders are required to complete the interaction - see warning. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const code = `_10 pub fun main(): Int {_10 return 5 + 4_10 }_10`;_10const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);_10console.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β
Name | Type | Description |
---|---|---|
address | Address | Address of the user account with or without a prefix (both formats are supported). |
Returnsβ
Type | Description |
---|---|
AccountObject | A JSON representation of a user account. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10const 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β
Name | Type | Default | Description |
---|---|---|---|
sealed | boolean | false | If the latest block should be sealed or not. See block states. |
id | string | ID of block to get. | |
height | int | Height of block to get. |
Returnsβ
Type | Description |
---|---|
BlockObject | A JSON representation of a block. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10await fcl.block(); // get latest finalized block_10await fcl.block({ sealed: true }); // get latest sealed block_10await fcl.block({_10 id: '0b1bdfa9ddaaf31d53c584f208313557d622d1fedee1586ffc38fb5400979faa',_10}); // get block by id_10await fcl.block({ height: 56481953 }); // get block by height
latestBlock
(Deprecated)β
A pre-built interaction that returns the latest block (optionally sealed or not).
Argumentsβ
Name | Type | Default | Description |
---|---|---|---|
isSealed | boolean | false | If the latest block should be sealed or not. See block states. |
Returnsβ
Type | Description |
---|---|
BlockObject | A JSON representation of a block. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10const 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β
Name | Type | Description |
---|---|---|
transactionId | string | A valid transaction id. |
Returnsβ
Name | Type | Description |
---|---|---|
snapshot() | function | Returns the current state of the transaction. |
subscribe(cb) | function | Calls the cb passed in with the new transaction on a status change. |
onceFinalized() | function | Provides the transaction once status 2 is returned. See Tranasaction Statuses. |
onceExecuted() | function | Provides the transaction once status 3 is returned. See Tranasaction Statuses. |
onceSealed() | function | Provides the transaction once status 4 is returned. See Tranasaction Statuses. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10_10const [txStatus, setTxStatus] = useState(null);_10useEffect(() => fcl.tx(txId).subscribe(setTxStatus));
Event Polling Utilityβ
events
β
A utility function that lets you set the transaction to get subsequent status updates (via polling) and the finalized result once available.
β οΈThe poll rate is set at 10000ms
and will update at that interval for getting new events.
Note:
β οΈfcl.eventPollRate
value could be set to change the polling rate of all events subcribers, check FCL Configuration for guide.
Argumentsβ
Name | Type | Description |
---|---|---|
eventName | string | A valid event name. |
Returnsβ
Name | Type | Description |
---|---|---|
subscribe(cb) | function | Calls the cb passed in with the new event. |
Usageβ
_10import * as fcl from '@onflow/fcl';_10// in some react component_10fcl.events(eventName).subscribe((event) => {_10 console.log(event);_10});
Examplesβ
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
β
Key | Value Type | Default | Description |
---|---|---|---|
addr | Address | null | The public address of the current user |
cid | string | null | Allows wallets to specify a content identifier for user metadata. |
expiresAt | number | null | Allows wallets to specify a time-frame for a valid session. |
f_type | string | 'USER' | A type identifier used internally by FCL. |
f_vsn | string | '1.0.0' | FCL protocol version. |
loggedIn | boolean | null | If the user is logged in. |
services | [ServiceObject] | [] | A list of trusted services that express ways of interacting with the current user's identity, including means to further discovery, authentication, authorization, or other kinds of interactions. |
AuthorizationObject
β
This type conforms to the interface required for FCL to authorize transaction on behalf o the current user.
Key | Value Type | Description |
---|---|---|
addr | Address | The address of the authorizer |
signingFunction | function | A function that allows FCL to sign using the authorization details and produce a valid signature. |
keyId | number | The index of the key to use during authorization. (Multiple keys on an account is possible). |
sequenceNum | number | A number that is incremented per transaction using they keyId. |
SignableObject
β
An object that contains all the information needed for FCL to sign a message with the user's signature.
Key | Value Type | Description |
---|---|---|
addr | Address | The address of the authorizer |
keyId | number | The index of the key to use during authorization. (Multiple keys on an account is possible). |
signature | function | A SigningFunction that can produce a valid signature for a user from a message. |
AccountObject
β
The JSON representation of an account on the Flow blockchain.
Key | Value Type | Description |
---|---|---|
address | Address | The address of the account |
balance | number | The FLOW balance of the account in 10^8. |
code | Code | The code of any Cadence contracts stored in the account. |
contracts | Object: Contract | An object with keys as the contract name deployed and the value as the the cadence string. |
keys | [KeyObject] | Any contracts deployed to this account. |
Address
β
Value Type | Description |
---|---|
string(formatted) | A valid Flow address should be 16 characters in length. A 0x prefix is optional during inputs. eg. f8d6e0586b0a20c1 |
ArgumentObject
β
An argument object created by fcl.arg(value,type)
Key | Value Type | Description |
---|---|---|
value | any | Any value to be used as an argument to a builder. |
xform | FType | Any of the supported types on Flow. |
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>
Parameter Name | Value Type | Description |
---|---|---|
arg | function | A function that returns an ArgumentObject - fcl.arg . |
t | FTypes | An object with acccess to all of the supported types on Flow. |
Returns
Value Type | Description |
---|---|
[fcl.args] | Array of fcl.args . |
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.
Parameter Name | Value Type | Description |
---|---|---|
account | AccountObject | The account of the user that is going to sign. |
Returns
Value Type | Description |
---|---|
Promise<[AuthorizationObject](#authorizationobject)> | The object that contains all the information needed by FCL to authorize a user's transaction. |
Usageβ
_19const authorizationFunction = async (account) => {_19 // authorization function need to return an account_19 const { address, keys } = account_19 const tempId = `${address}-${keys[process.env.minterAccountIndex]}`;_19 const keyId = Number(KEY_ID);_19 let signingFunction = async signable => {_19 return {_19 keyId,_19 addr: fcl.withPrefix(address),_19 signature: sign(process.env.FLOW_MINTER_PRIVATE_KEY, signable.message), // signing function, read below_19 }_19 }_19 return {_19 ...account,_19 address,_19 keyId,_19 tempId,_19 signingFunction,_19 }
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.
Parameter Name | Value Type | Description |
---|---|---|
message | string | The encoded string which needs to be used to produce the signature. |
addr | string | The encoded string which needs to be used to produce the signature. |
keyId | string | The encoded string which needs to be used to produce the signature. |
roles | string | The encoded string which needs to be used to produce the signature. |
voucher | object | The raw transactions information, can be used to create the message for additional safety and lack of trust in the supplied message. |
Returns
Value Type | Description |
---|---|
Promise<[SignableObject](#signableobject)> | The object that contains all the information needed by FCL to authorize a user's transaction. |
Usageβ
_31import * as fcl from '@onflow/fcl';_31import { ec as EC } from 'elliptic';_31import { SHA3 } from 'sha3';_31const ec: EC = new EC('p256');_31_31const produceSignature = (privateKey, msg) => {_31 const key = ec.keyFromPrivate(Buffer.from(privateKey, 'hex'));_31 const sig = key.sign(this.hashMsg(msg));_31 const n = 32;_31 const r = sig.r.toArrayLike(Buffer, 'be', n);_31 const s = sig.s.toArrayLike(Buffer, 'be', n);_31 return Buffer.concat([r, s]).toString('hex');_31};_31_31const signingFunction = ({_31 message, // The encoded string which needs to be used to produce the signature._31 addr, // The address of the Flow Account this signature is to be produced for._31 keyId, // The keyId of the key which is to be used to produce the signature._31 roles: {_31 proposer, // A Boolean representing if this signature to be produced for a proposer._31 authorizer, // A Boolean representing if this signature to be produced for a authorizer._31 payer, // A Boolean representing if this signature to be produced for a payer._31 },_31 voucher, // The raw transactions information, can be used to create the message for additional safety and lack of trust in the supplied message._31}) => {_31 return {_31 addr, // The address of the Flow Account this signature was produced for._31 keyId, // The keyId for which key was used to produce the signature._31 signature: produceSignature(message), // The hex encoded string representing the signature of the message._31 };_31};
Examples:β
TransactionObject
β
Key | Value Type | Description |
---|---|---|
args | object | A list of encoded Cadence values passed into this transaction. These have not been decoded by the JS-SDK. |
authorizers | [Address] | A list of the accounts that are authorizing this transaction to mutate to their on-chain account state. See more here. |
envelopeSignatures | [SignableObject] | A list of signatures generated by the payer role. See more here. |
gasLimit | number | The maximum number of computational units that can be used to execute this transaction. See more here. |
payer | Address | The account that pays the fee for this transaction. See more here. |
payloadSignatures | [SignableObject] | A list of signatures generated by the proposer and authorizer roles. See more here. |
proposalKey | [ProposalKey] | The account key used to propose this transaction |
referenceBlockId | string | A reference to the block used to calculate the expiry of this transaction. |
script | string | The UTF-8 encoded Cadence source code that defines the execution logic for this transaction |
TransactionRolesObject
β
Key Name | Value Type | Description |
---|---|---|
proposer | boolean | A Boolean representing if this signature to be produced for a proposer. |
authorizer | boolean | A Boolean representing if this signature to be produced for an authorizer. |
payer | boolean | A Boolean representing if this signature to be produced for a payer. |
For more on what each transaction role means, see singing roles.
TransactionStatusObject
β
Key | Value Type | Description |
---|---|---|
blockId | string | ID of the block that contains the transaction. |
events | [EventObject] | An array of events that were emitted during the transaction. |
status | TransactionStatus | The status of the transaction on the blockchain. |
statusString | TransactionStatus | The status as as descriptive text (e.g. "FINALIZED"). |
errorMessage | string | An error message if it exists. Default is an empty string '' . |
statusCode | number | The pass/fail status. 0 indicates the transaction succeeded, 1 indicates it failed. |
EventName
β
Value Type | Description |
---|---|
string(formatted) | A event name in Flow must follow the format A.{AccountAddress}.{ContractName}.{EventName} eg. A.ba1132bc08f82fe2.Debug.Log |
Contract
β
Value Type | Description |
---|---|
string(formatted) | A formatted string that is a valid cadence contract. |
KeyObject
β
This is the JSON representation of a key on the Flow blockchain.
Key | Value Type | Description |
---|---|---|
index | number | The address of the account |
publicKey | string | The public portion of a public/private key pair |
signAlgo | number | An index referring to one of ECDSA_P256 or ECDSA_secp256k1 |
hashAlgo | number | An index referring to one of SHA2_256 or SHA3_256 |
weight | number | A number between 1 and 1000 indicating the relative weight to other keys on the account. |
sequenceNumber | number | This number is incremented for every transaction signed using this key. |
revoked | boolean | If this key has been disabled for use. |
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
Key | Value Type | Description |
---|---|---|
address | Address | The address of the account |
keyIndex | number | The index of the account key being referenced |
sequenceNumber | number | The sequence number associated with this account key for this transaction |
BlockObject
β
The JSON representation of a key on the Flow blockchain.
Key | Value Type | Description |
---|---|---|
id | string | The id of the block. |
parentId | string | The id of the parent block. |
height | number | The height of the block. |
timestamp | object | Contains time related fields. |
collectionGuarantees | [CollectionGuaranteeObject] | Contains the ids of collections included in the block. |
blockSeals | [SealedBlockObject] | The details of which nodes executed and sealed the blocks. |
signatures | Uint8Array([numbers]) | All signatures. |
BlockHeaderObject
β
The subset of the BlockObject containing only the header values of a block.
Key | Value Type | Description |
---|---|---|
id | string | The id of the block. |
parentId | string | The id of the parent block. |
height | number | The height of the block. |
timestamp | object | Contains time related fields. |
CollectionGuaranteeObject
β
A collection that has been included in a block.
Key | Value Type | Description |
---|---|---|
collectionId | string | The id of the block. |
signatures | [SignatureObject] | All signatures. |
CollectionObject
β
A collection is a list of transactions that are contained in the same block.
Key | Value Type | Description |
---|---|---|
id | string | The id of the collection. |
transactionIds | [string] | The ids of the transactions included in the collection. |
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.
Key |
---|
tag |
transaction |
transactionStatus |
transactionId |
encodedData |
events |
account |
block |
blockHeader |
latestBlock |
collection |
Event Object
β
Key | Value Type | Description |
---|---|---|
blockId | string | ID of the block that contains the event. |
blockHeight | number | Height of the block that contains the event. |
blockTimestamp | string | The timestamp of when the block was sealed in a DateString format. eg. '2021-06-25T13:42:04.227Z' |
type | EventName | A string containing the event name. |
transactionId | string | Can be used to query transaction information, eg. via a Flow block explorer. |
transactionIndex | number | Used to prevent replay attacks. |
eventIndex | number | Used to prevent replay attacks. |
data | any | The data emitted from the event. |
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.
Status Code | Description |
---|---|
0 | Unknown |
1 | Transaction Pending - Awaiting Finalization |
2 | Transaction Finalized - Awaiting Execution |
3 | Transaction Executed - Awaiting Sealing |
4 | Transaction Sealed - Transaction Complete. At this point the transaction result has been committed to the blockchain. |
5 | Transaction Expired |
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.
Type | Example |
---|---|
UInt | fcl.arg(1, t.UInt) |
UInt8 | fcl.arg(8, t.UInt8) |
UInt16 | fcl.arg(16, t.UInt16) |
UInt32 | fcl.arg(32, t.UInt32) |
UInt64 | fcl.arg(64, t.UInt64) |
UInt128 | fcl.arg(128, t.UInt128) |
UInt256 | fcl.arg(256, t.UInt256) |
Int | fcl.arg(1, t.Int) |
Int8 | fcl.arg(8, t.Int8) |
Int16 | fcl.arg(16, t.Int16) |
Int32 | fcl.arg(32, t.Int32) |
Int64 | fcl.arg(64, t.Int64) |
Int128 | fcl.arg(128, t.Int128) |
Int256 | fcl.arg(256, t.Int256) |
Word8 | fcl.arg(8, t.Word8) |
Word16 | fcl.arg(16, t.Word16) |
Word32 | fcl.arg(32, t.Word32) |
Word64 | fcl.arg(64, t.Word64) |
UFix64 | fcl.arg("64.123", t.UFix64) |
Fix64 | fcl.arg("64.123", t.Fix64) |
String | fcl.arg("Flow", t.String) |
Character | fcl.arg("c", t.String) |
Bool | fcl.arg(true, t.String) |
Address | fcl.arg("0xABC123DEF456", t.Address) |
Optional | fcl.arg("Flow", t.Optional(t.String)) |
Array | fcl.args([ fcl.arg(["First", "Second"], t.Array(t.String)) ]) |
Dictionary | fcl.args([fcl.arg([{key: 1, value: "one"}, {key: 2, value: "two"}], t.Dictionary({key: t.Int, value: t.String}))]) |
Path | fcl.arg({ domain: "public", identifier: "flowTokenVault" }, t.Path) |
StreamConnection
β
A stream connection is an object for subscribing to generic data from any WebSocket data stream. This is the base type for all stream connections. Two channels, close
and error
, are always available, as they are used to signal the end of the stream and any errors that occur.
_20interface StreamConnection<ChannelMap extends { [name: string]: any }> {_20 // Subscribe to a channel_20 on<C extends keyof ChannelMap>(_20 channel: C,_20 listener: (data: ChannelMap[C]) => void,_20 ): this;_20 on(event: 'close', listener: () => void): this;_20 on(event: 'error', listener: (err: any) => void): this;_20_20 // Unsubscribe from a channel_20 off<C extends keyof ChannelMap>(_20 event: C,_20 listener: (data: ChannelMap[C]) => void,_20 ): this;_20 off(event: 'close', listener: () => void): this;_20 off(event: 'error', listener: (err: any) => void): this;_20_20 // Close the connection_20 close(): void;_20}
Usageβ
_13import { StreamConnection } from "@onflow/typedefs"_13_13const stream: StreamConnection = ..._13_13stream.on("close", () => {_13 // Handle close_13})_13_13stream.on("error", (err) => {_13 // Handle error_13})_13_13stream.close()
EventStream
β
An event stream is a stream connection that emits events and block heartbeats. Based on the connection parameters, heartbeats will be emitted at least as often as some fixed block height interval. It is a specific variant of a StreamConnection.
_10type EventStream = StreamConnection<{_10 events: Event[];_10 heartbeat: BlockHeartbeat;_10}>;
Usageβ
_14import { EventStream } from "@onflow/typedefs"_14_14const stream: EventStream = ..._14_14stream.on("events", (events) => {_14 // Handle events_14})_14_14stream.on("heartbeat", (heartbeat) => {_14 // Handle heartbeat_14})_14_14// Close the stream_14stream.close()
BlockHeartbeat
β
_10export interface BlockHeartbeat {_10 blockId: string;_10 blockHeight: number;_10 timestamp: string;_10}
Usageβ
_10import { BlockHeartbeat } from "@onflow/typedefs"_10_10const heartbeat: BlockHeartbeat = ...