Interaction Templates

Interaction Templates are a concept established in FLIP-934. Read the FLIP here

"Interaction" in this context refers to the higher order term establised in FLIP-934 that encompases a transaction and script, things that interact with the blockchain.

Overview

Interaction Templates establish a format for metadata that exists about an interaction. Interaction Templates can include:

• Human readable, internationalized messages about the interaction
• The Cadence code to carry out the interaction
• Information about arguments such as internationalized human readable messages and what the arguments act upon
• Contract dependencies the Interaction engages with, pinned to a version of them and their dependency tree

Applications and Wallets can use Interaction Templates and it's interaction metadata.

For example Applications and Wallets can extract the internationalized human readable messaging from an Interaction Template to display to their users prior to execution of the interaction.

For Applications

FCL mutate and query can accept an Interaction Template. FCL mutate and query will use the Interaction Template to:

• Extract the Cadence code to carry out the interaction
• Extract dependency configuration for the interaction (eg: Information about contract import addresses)

Here is an example of using mutate with an Interaction Template:

_10

import * as fcl from "@onflow/fcl"

_10

import myTransactionTemplate from "./my-transaction-template.template.json"

_10

_10

const txId = await fcl.mutate({

_10

template: myTransactionTemplate

_10

})

An Interaction Template can also be used with query:

_10

import * as fcl from "@onflow/fcl"

_10

import myScriptTemplate from "./my-script-template.template.json"

_10

_10

const info = await fcl.query({

_10

template: myScriptTemplate

_10

})

Interaction Templates can be resolved from remote locations:

_10

import * as fcl from "@onflow/fcl"

_10

_10

const txId = await fcl.mutate({

_10

template: "http://interactions.awesome-crypto-project.com/buy-nft"

_10

})

_10

_10

const nftInfo = await fcl.query({

_10

template: "http://interactions.awesome-crypto-project.com/read-nft",

_10

args: (arg, t) => [arg("nft-id", t.String)]

_10

})

FCL will resolve the template from the remote location before using it to execute its underlying transaction or script.

💡 By requesting an Interaction Template from an external location, applications have a mechanism to always retrieve the most up to date way of accomplishing an interaction.

By default FCL supports resolving Interaction Templates over http/https, but FCL can also be configured with various other ways to resolve Interaction Templates:

_10

import * as fcl from "@onflow/fcl"

_10

_10

await fcl.config().put("document.resolver.ipfs", async ({ url }) => {

_10

const jsonTemplate = getDocumentFromIPFS(url) // resolve interaction template from ipfs

_10

return jsonTemplate

_10

})

_10

_10

const txId = await fcl.mutate({

_10

template: "ipfs://IPFSHASHGOESHERE"

_10

})

For Wallets

Wallets can use Interaction Templates to:

• Display internationalized human readable information about a transaction to their users during signing
• Verify the dependencies of an Interaction Template have not changed since when the Interaction Template was created
• Using Interaction Template Audits, gain confidence in the correctness and safety of an Interaction Template and it's underlying transaction

When recieving a transaction to sign, wallets can query for an Interaction Template that corresponds to it.

Flow operates an "Interaction Template Discovery Service" which wallets can use to query for Interaction Templates. Anyone can run an "Interaction Template Discovery Service" and wallets can choose to query from any of them.

_18

const cadence = cadenceFromTransactionToSign

_18

const network = "mainnet" // "mainnet" | "testnet"

_18

_18

const cadence_base64 = btoa(cadence)

_18

_18

const interactionTemplate = await fetch(

_18

"https://flix.flow.com/v1/templates/search",

_18

{

_18

method: "POST",

_18

headers: {

_18

"Content-Type": "application/json"

_18

}

_18

body: JSON.stringify({

_18

cadence_base64,

_18

network

_18

})

_18

}

_18

)

📖 For more on the "Interaction Template Discovery Service" that Flow operates, see here

❗️ Not all transactions will have a corresponding Interaction Template. Wallets are encouraged to always support signing transactions that do not have a corresponding Interaction Template, or if they fail to discover one.

Once a wallet has a corresponding Interaction Template for a given transaction, they may also may wish to verify that the transaction it represents is safe to sign, and that the Interaction Template is accurate for that transaction.

To do so, wallets can rely on themselves, along with external Interaction Template Auditors to gain confidence in the Interaction Template and it's underlying transaction. Interaction Template Auditors are entities that audit Interaction Templates for correctness and safety.

💡 Anyone can be an Interaction Template Auditor. Wallets can choose auditors they trust, if any.

Wallets can specify auditors it trusts to FCL by configuring FCL with the address of each auditor:

_11

import * as fcl from "@onflow/fcl"

_11

_11

await fcl.config().put("flow.network", "mainnet")

_11

_11

const auditorA_FlowAddress = "0xABC123DEF456"

_11

const auditorB_FlowAddress = "0xFFAA1212DEFF"

_11

_11

await fcl.config().put("flow.auditors", [

_11

auditorA_FlowAddress,

_11

auditorB_FlowAddress

_11

])

Wallets can check if the auditors they configured FCL with have audited a given Interaction Template:

_14

import * as fcl from "@onflow/fcl"

_14

import myTransactionTemplate from "./my-transaction-template.template.json"

_14

_14

const audits = await fcl.InteractionTemplateUtils

_14

.getInteractionTemplateAudits({

_14

template: myTransactionTemplate

_14

})

_14

_14

/**

_14

* audits = {

_14

* "0xABC123DEF456": true,

_14

* "0xFFAA1212DEFF": false

_14

* }

_14

** /

The Flow team operates these auditor accounts:

Flow Team Auditor Accounts	Address
TestNet	0xf78bfc12d0a786dc
MainNet	0xfd100e39d50a13e6

Since not all auditors that a wallet trusts may have audited a given Interaction Template, trusting multiple auditors can increase the chance that at least one of the trusted auditors has audited the Interaction Template.

❗️ Auditors can revoke audits at any time, so be sure to always check an Interaction Template's audit status.

Since contracts on Flow are mutable, wallets may additionally wish to verify that none of the dependency tree for the transaction an Interaction Template represents has changed since when it was created and of what it was audited against.

_10

import * as fcl from "@onflow/fcl"

_10

import myTransactionTemplate from "./my-transaction-template.template.json"

_10

_10

const hasDependencyTreeChanged = await fcl.InteractionTemplateUtils

_10

.verifyDependencyPinsSameAtLatestSealedBlock({

_10

template: myTransactionTemplate

_10

})

If the dependency tree has changed, wallets may choose to disregard the Interaction Template (and it's audits).

Once the Interaction Template has been sufficiently audited by auditors the wallet trusts, and it's dependency tree determined unchanged since the interaction was created and audited against, then the wallet can use the Interaction Template with greater confidence in it's correctness and safety.

The wallet may then decide to render human readable information about the transaction such as:

• Internationalized 'title' and 'description' of the transaction
• Internationalized 'title' for each of the transactions arguments alongside the arguments value

The wallet may then also make the status of it's audits known to the user in their UI. This allows the user to have greater confidence in the safety of the transaction.

Data Structure

The following is an example Interaction Template that corresponds to a "Transfer FLOW" transaction:

_66

{

_66

"f_type": "InteractionTemplate",

_66

"f_version": "1.0.0",

_66

"id": "290b6b6222b2a77b16db896a80ddf29ebd1fa3038c9e6625a933fa213fce51fa",

_66

"data": {

_66

"type": "transaction",

_66

"interface": "",

_66

"messages": {

_66

"title": {

_66

"i18n": {

_66

"en-US": "Transfer Tokens"

_66

}

_66

},

_66

"description": {

_66

"i18n": {

_66

"en-US": "Transfer tokens from one account to another"

_66

}

_66

}

_66

},

_66

"cadence": "import FungibleToken from 0xFUNGIBLETOKENADDRESS\ntransaction(amount: UFix64, to: Address) {\nlet vault: @FungibleToken.Vault\nprepare(signer: &Account) {\nself.vault <- signer\n.borrow<&{FungibleToken.Provider}>(from: /storage/flowTokenVault)!\n.withdraw(amount: amount)\n}\nexecute {\ngetAccount(to)\n.capabilities.get(/public/flowTokenReceiver)!\n.borrow<&{FungibleToken.Receiver}>()!\n.deposit(from: <-self.vault)\n}\n}",

_66

"dependencies": {

_66

"0xFUNGIBLETOKENADDRESS": {

_66

"FungibleToken": {

_66

"mainnet": {

_66

"address": "0xf233dcee88fe0abe",

_66

"fq_address": "A.0xf233dcee88fe0abe.FungibleToken",

_66

"contract": "FungibleToken",

_66

"pin": "83c9e3d61d3b5ebf24356a9f17b5b57b12d6d56547abc73e05f820a0ae7d9cf5",

_66

"pin_block_height": 34166296

_66

},

_66

"testnet": {

_66

"address": "0x9a0766d93b6608b7",

_66

"fq_address": "A.0x9a0766d93b6608b7.FungibleToken",

_66

"contract": "FungibleToken",

_66

"pin": "83c9e3d61d3b5ebf24356a9f17b5b57b12d6d56547abc73e05f820a0ae7d9cf5",

_66

"pin_block_height": 74776482

_66

}

_66

}

_66

}

_66

},

_66

"arguments": {

_66

"amount": {

_66

"index": 0,

_66

"type": "UFix64",

_66

"messages": {

_66

"title": {

_66

"i18n": {

_66

"en-US": "The amount of FLOW tokens to send"

_66

}

_66

}

_66

}

_66

},

_66

"to": {

_66

"index": 1,

_66

"type": "Address",

_66

"messages": {

_66

"title": {

_66

"i18n": {

_66

"en-US": "The Flow account the tokens will go to"

_66

}

_66

}

_66

}

_66

}

_66

}

_66

}

_66

}