LLM Notice: This documentation site supports content negotiation for AI agents. Request any page with Accept: text/markdown or Accept: text/plain header to receive Markdown instead of HTML. Alternatively, append ?format=md to any URL. All markdown files are available at /md/ prefix paths. For all content in one file, visit /llms-full.txt
Skip to main content

Flow Interaction Templates (FLIX)

FLIX helps developers reuse current Cadence transactions and scripts to easily integrate with current Cadence smart contracts. Get more information about Flow Interaction Templates (FLIX).

Introduction​

The Flow CLI provides a flix command with a few sub commands execute and package. (FLIX) are a standard for Cadence scripts and transaction distribution, and metadata in a way that is consumable by tooling and wallets. Auditors in the ecosystem can audit FLIX for correctness and safety.


_10
>flow flix
_10
execute, generate, package
_10
_10
Usage:
_10
flow flix [command]
_10
_10
Available Commands:
_10
execute execute FLIX template with a given id, name, local filename, or url
_10
generate generate FLIX json template given local Cadence filename
_10
package package file for FLIX template fcl-js is default

Execute​

The Flow CLI provides a flix command to execute FLIX. The Cadence that's executed in the FLIX can be a transaction or script.


_10
flow flix execute <query> [<argument> <argument>...] [flags]

warning

A FLIX template might only support testnet or mainnet. Generally, emulator is not supported. This can be the case if the FLIX template relies on contract dependencies.

Queries can be a FLIX id, name, url or path to a local FLIX file.

Execute use​


_10
# Execute a FLIX transaction by name on Testnet
_10
flow flix execute transfer-flow 5.0 "0x123" --network testnet --signer "testnet-account"


_10
# Execute a FLIX script by id on Testnet
_10
flow flix execute bd10ab0bf472e6b58ecc0398e9b3d1bd58a4205f14a7099c52c0640d9589295f --network testnet


_10
# Execute a local FLIX script by path on Testnet
_10
flow flix execute ./multiply.template.json 2 3 --network testnet

The Flow CLI provides a flix command to package up generated plain and simple JavaScript. This JavaScript uses FCL (Flow Client Library) to call the cadence the FLIX is based on.

info

Currently, flix package command only supports generating FCL-specific JavaScript and TypeScirpt. There are plans to support other languages like golang.


_10
flow flix package <query> [flags]

Generate​

Generate FLIX json file. This command will take in a Cadence file and produce a FLIX json file. There are two ways to provide metadata to populate the FLIX json structure.

  • Use --pre-fill flag to pass in a pre populated FLIX json structure
  • Use --exclude-networks flag to specify excluded networks when you generate a FLIX template. For example, --exclude-networks testnet,mainnet
warning

When you generate a FLIX template, make sure all contract dependencies have been deployed to the supported networks. Add any aliases to your flow.json that you need to populate dependencies. Verify all dependencies were populated after you generate the FLIX template.

Generate use​


_10
# Generate FLIX json file using cadence transaction or script, this example is not using a prefilled json file so will not have associated message metadata
_10
flow flix generate cadence/transactions/update-helloworld.cdc --save cadence/templates/update-helloworld.template.json

Example of Cadence simple, no metadata associated:


_10
_10
import "HelloWorld"
_10
access(all) fun main(): String {
_10
return HelloWorld.greeting
_10
}

Cadence doc pragma:​

It's recommended to use pragma to set the metadata for the script or transaction.

View more information about Cadence Doc Pragma FLIP.

A pragma is short for "pragmatic information", it's special instructions to convey information to a processor in this case the utility that generates FLIX.


_19
import "HelloWorld"
_19
_19
#interaction (
_19
version: "1.1.0",
_19
title: "Update Greeting",
_19
description: "Update the greeting on the HelloWorld contract",
_19
language: "en-US",
_19
)
_19
_19
transaction(greeting: String) {
_19
_19
prepare(acct: &Account) {
_19
log(acct.address)
_19
}
_19
_19
execute {
_19
HelloWorld.updateGreeting(newGreeting: greeting)
_19
}
_19
}

info

Cadence v0.42.7 supports additional Cadence pragma functionality that FlIX utility can use to generate FLIX. It will support parameters "title" and "description"

The json metadata that results is extracted from Cadence Doc Pragma.


_39
{
_39
"f_type": "InteractionTemplate",
_39
"f_version": "1.1.0",
_39
"id": "",
_39
"data": {
_39
"type": "transaction",
_39
"interface": "",
_39
"messages": [
_39
{
_39
"key": "title",
_39
"i18n": [
_39
{
_39
"tag": "en-US",
_39
"translation": "Update Greeting"
_39
}
_39
]
_39
},
_39
{
_39
"key": "description",
_39
"i18n": [
_39
{
_39
"tag": "en-US",
_39
"translation": "Update the greeting on the HelloWorld contract"
_39
}
_39
]
_39
}
_39
],
_39
"cadence": {},
_39
"dependencies": [],
_39
"parameters": [
_39
{
_39
"label": "greeting",
_39
"index": 0,
_39
"type": "String",
_39
"messages": []
_39
}
_39
]
_39
}
_39
}

Example of when you use a prefilled FLIX json file. No need to use Cadence pragma when you use a prefilled FLIX json file. This method separates FLIX specific information from the transaction or script Cadence. Use the flow flix generate command:


_10
flow flix generate cadence/scripts/read-helloworld.cdc --pre-fill cadence/templates/read-helloworld.prefill.json --save cadence/templates/read-helloworld.template.json

With a pre-filled FLIX template, the cadence can be simple but no metadata accompanies it.


_10
import "HelloWorld"
_10
access(all) fun main(): String {
_10
return HelloWorld.greeting
_10
}

Example of json prefill file with message metadata:


_29
{
_29
"f_type": "InteractionTemplate",
_29
"f_version": "1.1.0",
_29
"id": "",
_29
"data": {
_29
"type": "script",
_29
"interface": "",
_29
"messages": [
_29
{
_29
"key": "title",
_29
"i18n": [
_29
{
_29
"tag": "en-US",
_29
"translation": "Get Greeting"
_29
}
_29
]
_29
},
_29
{
_29
"key": "description",
_29
"i18n": [
_29
{
_29
"tag": "en-US",
_29
"translation": "Call HelloWorld contract to get greeting"
_29
}
_29
]
_29
}
_29
]
_29
}
_29
}

The FLIX json file that results after generation:


_62
{
_62
"f_type": "InteractionTemplate",
_62
"f_version": "1.1.0",
_62
"id": "fd9abd34f51741401473eb1cf676b105fed28b50b86220a1619e50d4f80b0be1",
_62
"data": {
_62
"type": "script",
_62
"interface": "",
_62
"messages": [
_62
{
_62
"key": "title",
_62
"i18n": [
_62
{
_62
"tag": "en-US",
_62
"translation": "Get Greeting"
_62
}
_62
]
_62
},
_62
{
_62
"key": "description",
_62
"i18n": [
_62
{
_62
"tag": "en-US",
_62
"translation": "Call HelloWorld contract to get greeting"
_62
}
_62
]
_62
}
_62
],
_62
"cadence": {
_62
"body": "import \"HelloWorld\"\naccess(all) fun main(): String {\n return HelloWorld.greeting\n}\n",
_62
"network_pins": [
_62
{
_62
"network": "testnet",
_62
"pin_self": "41c4c25562d467c534dc92baba92e0c9ab207628731ee4eb4e883425abda692c"
_62
}
_62
]
_62
},
_62
"dependencies": [
_62
{
_62
"contracts": [
_62
{
_62
"contract": "HelloWorld",
_62
"networks": [
_62
{
_62
"network": "testnet",
_62
"address": "0xe15193734357cf5c",
_62
"dependency_pin_block_height": 137864533,
_62
"dependency_pin": {
_62
"pin": "aad46badcab3caaeb4f0435625f43e15bb4c15b1d55c74a89e6f04850c745858",
_62
"pin_self": "a06b3cd29330a3c22df3ac2383653e89c249c5e773fd4bbee73c45ea10294b97",
_62
"pin_contract_name": "HelloWorld",
_62
"pin_contract_address": "0xe15193734357cf5c",
_62
"imports": []
_62
}
_62
}
_62
]
_62
}
_62
]
_62
}
_62
],
_62
"parameters": null
_62
}
_62
}

Package​

Queries can be a FLIX url or path to a local FLIX file. This command leverages FCL which will execute FLIX cadence code. Package files can be generated in JavaScript or TypeScript.

warning

Currently, package doesn't support id, name flix query.

Package use​


_10
# Generate packaged code that leverages FCL to call the Cadence transaction code, `--save` flag will save the output to a specific file
_10
flow flix package transfer-flow --save ./package/transfer-flow.js


_10
# Generate package code for a FLIX script using id, since there is no saving file, the result will display in terminal
_10
flow flix package bd10ab0bf472e6b58ecc0398e9b3d1bd58a4205f14a7099c52c0640d9589295f


_10
# Generate package code using local template file to save in a local file
_10
flow flix package ./multiply.template.json --save ./multiply.js


_10
# Generate package code using local template file to save in a local typescript file
_10
flow flix package ./multiply.template.json --lang ts --save ./multiply.ts

Example package output​


_10
flow flix package https://flix.flow.com/v1/templates\?name\=transfer-flow


_24
/**
_24
This binding file was auto generated based on FLIX template v1.0.0.
_24
Changes to this file might get overwritten.
_24
Note fcl version 1.3.0 or higher is required to use templates.
_24
**/
_24
_24
import * as fcl from '@onflow/fcl';
_24
const flixTemplate = 'https://flix.flow.com/v1/templates?name=transfer-flow';
_24
_24
/**
_24
* Transfer tokens from one account to another
_24
* @param {Object} Parameters - parameters for the cadence
_24
* @param {string} Parameters.amount - The amount of FLOW tokens to send: UFix64
_24
* @param {string} Parameters.to - The Flow account the tokens will go to: Address
_24
* @returns {Promise<string>} - returns a promise which resolves to the transaction id
_24
*/
_24
export async function transferTokens({ amount, to }) {
_24
const transactionId = await fcl.mutate({
_24
template: flixTemplate,
_24
args: (arg, t) => [arg(amount, t.UFix64), arg(to, t.Address)],
_24
});
_24
_24
return transactionId;
_24
}


_10
# Generate TypeScript version of package file
_10
flow flix package https://flix.flow.com/v1/templates?name=transfer-flow --lang ts


_31
/**
_31
This binding file was auto generated based on FLIX template v1.1.0.
_31
Changes to this file might get overwritten.
_31
Note fcl version 1.9.0 or higher is required to use templates.
_31
**/
_31
_31
import * as fcl from '@onflow/fcl';
_31
const flixTemplate = 'https://flix.flow.com/v1/templates?name=transfer-flow';
_31
_31
interface TransferTokensParams {
_31
amount: string; // The amount of FLOW tokens to send
_31
to: string; // The Flow account the tokens will go to
_31
}
_31
_31
/**
_31
* transferTokens: Transfer tokens from one account to another
_31
* @param string amount - The amount of FLOW tokens to send
_31
* @param string to - The Flow account the tokens will go to
_31
* @returns {Promise<string>} - Returns a promise that resolves to the transaction ID
_31
*/
_31
export async function transferTokens({
_31
amount,
_31
to,
_31
}: TransferTokensParams): Promise<string> {
_31
const transactionId = await fcl.mutate({
_31
template: flixTemplate,
_31
args: (arg, t) => [arg(amount, t.UFix64), arg(to, t.Address)],
_31
});
_31
_31
return transactionId;
_31
}

warning

Notice that fcl v1.9.0 is needed to use FLIX v1.1 templates

Resources​

To find out more about FLIX, see the read the FLIP.

For a list of all templates, check out the FLIX template repository.

To generate a FLIX, see the FLIX CLI readme.

Arguments​

  • Name: argument
  • Valid input: valid FLIX

Input argument value that match types which correspond in the source code and passed in the same order. To pass a nil value to optional arguments, you can execute the flow FLIX execute script like this: flow flix execute template.json nil.

Flags​

Arguments JSON​

  • Flag: --args-json
  • Valid inputs: arguments in JSON-Cadence form.
  • Example: flow flix execute template.script.json '[{"type": "String", "value": "Hello World"}]'

Arguments passed to the Cadence script in the Cadence JSON format. Cadence JSON format contains type and value keys and is documented here.

Pre Fill​

  • Flag: --pre-fill
  • Valid inputs: a json file in the FLIX json structure FLIX json format

Block Height​

  • Flag: --block-height
  • Valid inputs: a block height number

Block ID​

  • Flag: --block-id
  • Valid inputs: a block ID

Signer​

  • Flag: --signer
  • Valid inputs: the name of an account defined in the configuration (flow.json)

Specify the name of the account that will be used to sign the transaction.

Proposer​

  • Flag: --proposer
  • Valid inputs: the name of an account defined in the configuration (flow.json)

Specify the name of the account that will be used as the proposer in the transaction.

Payer​

  • Flag: --payer
  • Valid inputs: the name of an account defined in the configuration (flow.json)

Specify the name of the account that will be used as the payer in the transaction.

Authorizer​

  • Flag: --authorizer
  • Valid inputs: the name of a single or multiple comma-separated accounts defined in the configuration (flow.json)

Specify the name of the account(s) that will be used as authorizer(s) in the transaction. If you want to provide multiple authorizers, use commas to separate them (for example, alice,bob)

Compute limit​

  • Flag: --compute-limit
  • Valid inputs: an integer greater than zero.
  • Default: 1000

Specify the compute unit (gas) limit for this transaction.

Host​

  • Flag: --host
  • Valid inputs: an IP address or hostname.
  • Default: 127.0.0.1:3569 (Flow Emulator)

Specify the hostname of the Access API that will be used to execute the command. This flag overrides any host defined by the --network flag.

Network key​

  • Flag: --network-key
  • Valid inputs: A valid network public key of the host in hex string format

Specify the network public key of the Access API that will be used to create a secure GRPC client when you execute the command.

Network​

  • Flag: --network
  • Short Flag: -n
  • Valid inputs: the name of a network defined in the configuration (flow.json)
  • Default: emulator

Specify which network you want the command to use for execution.

Filter​

  • Flag: --filter
  • Short Flag: -x
  • Valid inputs: a case-sensitive name of the result property.

Specify any property name from the result you want to return as the only value.

Output​

  • Flag: --output
  • Short Flag: -o
  • Valid inputs: json, inline

Specify the format of the command results.

Save​

  • Flag: --save
  • Short Flag: -s
  • Valid inputs: a path in the current filesystem.

Specify the filename where you want to save the result.

Log​

  • Flag: --log
  • Short Flag: -l
  • Valid inputs: none, error, debug
  • Default: info

Specify the log level. Control how much output you want to see during command execution.

Configuration​

  • Flag: --config-path
  • Short Flag: -f
  • Valid inputs: a path in the current filesystem.
  • Default: flow.json

Specify the path to the flow.json configuration file. You can use the -f flag multiple times to merge several configuration files.

Version Check​

  • Flag: --skip-version-check
  • Default: false

Skip version check during start up to speed up process for slow connections.

Rate this page