status | flip | authors | sponsor | updated |
---|---|---|---|---|
approved |
163 |
Bjarte Karslen ([email protected]), Jeffrey Doyle ([email protected]), Tom Haile ([email protected]) |
Jeffrey Doyle ([email protected]) |
2023-04-06 |
This FLIP proposes a new standard for how Cadence transaction and script developers can declare static metadata about a transaction or script, in a machine parsable way, with the goal of this metadata to aid in the generation of a corresponding Interaction Template for the transaction or script.
This standard is to be called "Interaction Template Cadence Doc".
In order to increase adoption of Interaction Templates across the Flow ecosystem, the creation of developer friendly tools and processes such as this standard for the generation of Interaction Templates is required.
Developers benefit from Interaction Template Cadence Doc by having an easy way to declare static metadata for their transactions and scripts. This allows them to store static metadata alongside the Cadence code for the transaction or script in the Interaction Template Cadence Doc comment. This way, developers can iterate on their transactions and scripts, and only need to declare their metadata once while being able to change it as required or desired.
With the creation of tooling for generating Interaction Templates through parsing Interaction Template Cadence Doc, automated ways for creating Interaction Templates can be created; such as, Flow CLI integration for generating an Interaction Template from a cadence transaction or script file that has Interaction Template Cadence Doc, or a Flow CLI file watcher mechanism which autogenerates a transaction or scripts corresponding Interaction Template every time the transaction or script with Interaction Template Cadence Doc changes.
Interaction Template Cadence Doc can be included in a Cadence transaction or script, below all transaction/script imports and above the transaction
or main
function declaration, with no new line in between. This documentation format leverages existing Cadence support and parsing of pragma.
Interaction Template Cadence Doc supports the following format:
-
#interaction()
declares the Interaction Template Cadence Doc pragma. The metadata will be enclosed within. -
version
the version of FLIX, needed to understand the structure to be generated. -
title
the title of the template, needs to be in the language declared bylanguage
-
language
declares the default BCP-47 language tag for all messages in the Interaction Template Cadence Doc (defaults to 'en-US'). -
parameters
declares information about a transaction/script parametersParameter name
the name of the field that cooresponds to the name of the parameter in the transaction or script.Parameter title
the title of the field a human readable short message to associate with the parameterPparameter description
optional description of the field a human readable message to associate with the parameter
This is an example of Interaction Template Cadence Doc for a transaction:
import "FungibleToken"
import "FlowToken"
#interaction(
version: "1.1.0",
title: "Transfer Tokens",
description: "Transfer tokens from one account to another",
language: "en-US",
parameters: [
Parameter(
name: "amount",
title: "Amount",
description: "The amount of FLOW tokens to send"
),
Parameter(
name: "to",
title: "To",
description: "The Flow account the tokens will go to"
)
],
)
transaction(amount: UFix64, to: Address) {
let vault: @FungibleToken.Vault
prepare(signer: AuthAccount) {
self.vault <- signer
.borrow<&{FungibleToken.Provider}>(from: /storage/flowTokenVault)!
.withdraw(amount: amount)
}
execute {
getAccount(to)
.getCapability(/public/flowTokenReceiver)!
.borrow<&{FungibleToken.Receiver}>()!
.deposit(from: <-self.vault)
}
}
This is an example of Interaction Template Cadence Doc for a script:
import "FungibleToken"
import "FlowToken"
#interaction(
version: "1.1.0",
title: "Flow Token Balance",
description: "Get account Flow Token balance",
language: "en-US",
parameters: [
Parameter(
name: "address",
title: "Address",
description: "Get Flow token balance of Flow account"
)
],
)
pub fun main(address: Address): UFix64 {
let account = getAccount(address)
let vaultRef = account.getCapability(/public/flowTokenBalance).borrow<&FlowToken.Vault{FungibleToken.Balance}>() ?? panic("Failed to borrow Flow Token balance reference")
return vaultRef.balance
}
- Since Interaction Template Cadence Doc lives inside the transaction/script, it unnecessarily persists information on the blockchain that is not relevant to the execution of the transaction itself.
- Flow Interaction Templates
- Any breaking changes to Interaction Templates must have a corresponding update to Interaction Template Cadence Doc to accommodate them.
- Interaction Template Cadence Doc will be maintained by those working on Interaction Templates.
- Interaction Template Cadence Doc will need to be added to tutorials and documentation provided to developers so they can use it when creating transactions and scripts on Flow.
- Interaction Template Cadence Doc will need to maintain compatibility with the latest specification of the Flow Interaction Template data structure.
- Interaction Template Cadence Doc is built to resemble best practices from Javadoc and JSDoc.
- Are there other viable formats for declaring static metadata for a transaction or script?