Flow Interaction Templates (FLIX)

Previous << Cadence Linter
Next >> Cadence Boilerplate

開発者が既存のCadenceトランザクションとスクリプトを再利用し、それらを既存のCadenceスマートコントラクトに簡単に統合できるようにすることを、FLIX(Flow Interaction Templates)は助けます。詳細はFlow Interaction Templatesをご覧ください。

Introduction

Flow CLIはflixコマンドと、そのサブコマンドのexecuteとpackageを提供しています。Flow Interaction Templates (FLIXに慣れ親しんでください。FLIXは、Cadenceスクリプトやトランザクション、メタデータを、ツールやウォレットで利用可能な形で、配布するためのスタンダードです。FLIXは、エコシステム内の監査機関によって、正確性と安全性を監査することができます。

>flow flix
execute, generate, package

Usage:
  flow flix [command]

Available Commands:
  execute     execute FLIX template with a given id, name, local filename, or url
  generate    generate FLIX json template given local Cadence filename
  package     package file for FLIX template fcl-js is default

Execute

Flow CLIは、FLIXをexecuteするflixコマンドを提供しています。FLIXで実行されるCadenceは、トランザクションまたはスクリプトです。

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

WARNING
FLIXテンプレートは、テストネットおよび/またはメインネットのみをサポートしている場合があります。一般的に、エミュレータはサポートされていません。もし、FLIXテンプレートがスマートコントラクトの依存関係に依存している場合、このようなケースになる可能性があります。

クエリ(query)は、FLIXのid、 name、 url、またはローカルFLIXファイルへのpathがなり得ます。

Execute Usage

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

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

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

Flow CLIはpackageというflixコマンドを提供しており、生成されたプレーンでシンプルなJavaScriptをパッケージ化できます。このJavaScriptは、FCL (Flow Client Library) を使用して、Flow Interaction Templates (FLIX) がベースとしているCadenceファイルをCallします。

INFO
現在、flix packageコマンドは、FCL（Flow Client Library）固有のJavaScriptとTypeScirptの生成のみをサポートしていますが、golangなどの他の言語をサポートする計画があります。

flow flix package <query> [flags]

Generate

FLIX jsonファイルを生成します。このコマンドはCadenceファイルを受け取り、FLIX jsonファイルを生成します。FLIX json構造にメタデータを埋め込むには、2つの方法があります。

• --pre-fillフラグを使用して、事前に埋め込まれたFLIX json構造を渡します
• --exclude-networksフラグを使用して、FLIXテンプレートを生成する際に除外するネットワークを指定します。例：--exclude-networks testnet,mainnet

WARNING
FLIXテンプレートを生成する際には、すべてのスマートコントラクト依存関係がサポート対象のネットワークにデプロイされていることを確認してください。flow.jsonに依存関係を埋め込むために必要なエイリアスを追加してください。生成後にすべての依存関係が埋め込まれていることを確認してください。

Generate Usage

# 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 
flow flix generate cadence/transactions/update-helloworld.cdc --save cadence/templates/update-helloworld.template.json

シンプル、メタデータなしのCadenceの例

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

Cadence Doc Pragma:

スクリプトやトランザクションに対してメタデータを設定するには、プラグマ(pragma)を使用することをお勧めします。より詳しくは、Cadence Doc Pragma FLIPをご覧ください。

pragmaは"実用的な情報(pragmatic information)"の略語であり、プロセッサに情報を伝える特別な指示です（この場合、FLIXを生成しているユーティリティ）。

import "HelloWorld"

#interaction (
    version: "1.1.0",
    title: "Update Greeting",
    description: "Update the greeting on the HelloWorld contract",
    language: "en-US",
)

transaction(greeting: String) {

  prepare(acct: &Account) {
    log(acct.address)
  }

  execute {
    HelloWorld.updateGreeting(newGreeting: greeting)
  }
}

INFO
Cadence v0.42.7は、追加のFlIXユーティリティがFLIXを生成する際に使用できるCadenceプラグマ機能をサポートします。それはパラメータ"title"と"description"をサポートします。

生成されたjsonメタデータは、Cadence Doc Pragmaから抽出されます。

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

事前埋め込みされた FLIX json ファイルの使用例。事前埋め込みされた FLIX json ファイルを使用する場合は、Cadence プラグマを使用する必要はありません。このメソッドは、FLIX 固有の情報をトランザクションやスクリプト Cadenceファイル から分離します。flow flix generateコマンドを使用します。

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

事前埋め込みされたFLIXテンプレートを使用することで、Cadenceファイルはシンプルになりますが、メタデータが付随しません。

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

メッセージメタデータを含むjson事前埋め込みファイルの例：

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

生成後のFLIX jsonファイル：

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

Package

Queryは、FLIXのurlか、ローカルのFLIXファイルへのpathです。このコマンドはFCLを活用し、FLIXのCadenceコードを実行します。パッケージファイルはJavaScriptかTypeScriptで生成できます。

WARNING
現在、packageはid、name のflix クエリをサポートしていません。

Package Usage

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

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

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

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

Example Package Output

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

/**
    This binding file was auto generated based on FLIX template v1.0.0. 
    Changes to this file might get overwritten.
    Note fcl version 1.3.0 or higher is required to use templates. 
**/

import * as fcl from "@onflow/fcl"
const flixTemplate = "https://flix.flow.com/v1/templates?name=transfer-flow"

/**
* Transfer tokens from one account to another
* @param {Object} Parameters - parameters for the cadence
* @param {string} Parameters.amount - The amount of FLOW tokens to send: UFix64
* @param {string} Parameters.to - The Flow account the tokens will go to: Address
* @returns {Promise<string>} - returns a promise which resolves to the transaction id
*/
export async function transferTokens({amount, to}) {
  const transactionId = await fcl.mutate({
    template: flixTemplate,
    args: (arg, t) => [arg(amount, t.UFix64), arg(to, t.Address)]
  });

  return transactionId
}

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

/**
    This binding file was auto generated based on FLIX template v1.1.0. 
    Changes to this file might get overwritten.
    Note fcl version 1.9.0 or higher is required to use templates. 
**/

import * as fcl from "@onflow/fcl"
const flixTemplate = "https://flix.flow.com/v1/templates?name=transfer-flow"

interface TransferTokensParams {
  amount: string; // The amount of FLOW tokens to send
  to: string; // The Flow account the tokens will go to
}

/**
* transferTokens: Transfer tokens from one account to another
* @param string amount - The amount of FLOW tokens to send
* @param string to - The Flow account the tokens will go to
* @returns {Promise<string>} - Returns a promise that resolves to the transaction ID
*/
export async function transferTokens({amount, to}: TransferTokensParams): Promise<string> {
  const transactionId = await fcl.mutate({
    template: flixTemplate,
    args: (arg, t) => [arg(amount, t.UFix64), arg(to, t.Address)]
  });

  return transactionId
}

WARNING
FLIX v1.1テンプレートを使用するには、fcl v1.9.0が必要です。

Resources

FLIXについてさらに詳しく知りたい場合は、read the FLIPを参照してください。

すべてのテンプレートの一覧については、FLIXテンプレートリポジトリをご覧ください。

FLIXを生成するには、FLIX CLI readmeを参照してください。

Arguments

• Name: argument
• Valid input: valid FLIX

ソースコード内の対応する型に一致した入力引数値を、同じ順序で渡します。FLIX実行スクリプトを次のようにして実行することで、オプショナル引数にnil値を渡すことができます: 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"}]'

Cadenceスクリプトに渡される引数は、Cadence JSON形式で指定します。Cadence JSON形式には、typeおよびvalueのキーが含まれ、こちらで説明されています。

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)

トランザクションに署名する際に使用するアカウントの名前を指定します。

Proposer

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

トランザクションに署名する際に提案者として使用するアカウントの名前を指定します。

Payer

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

トランザクションに署名する際にトランザクションフィーの支払者として使用するアカウントの名前を指定します。

Authorizer

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

トランザクションで承認者として使用されるアカウントの名前を指定します。複数の承認者を使用する場合は、カンマで区切ってください（例：alice,bob）

Gas Limit

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

このトランザクションのガスリミットを指定します。

Host

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

コマンドの実行に使用する Access API のホスト名を指定します。このフラグは、--network フラグで定義されたホストをすべて上書きします。

Network Key

• Flag: --network-key
• Valid inputs: ホストの有効なネットワーク公開鍵の 16 進数文字列

コマンドを実行する際に、セキュアなGRPCクライアントを作成するために使用するAccess APIのネットワーク公開鍵を指定します。

Network

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

どのネットワークに対してコマンドを実行するのかを指定します。

Filter

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

結果から、唯一の値として取得したいプロパティの名前を指定します。

Output

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

コマンド結果のフォーマットを指定します。

Save

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

結果を保存したいファイル名を指定してください。

Log

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

ログレベルを指定します。コマンド実行中に表示する出力を制御します。

Configuration

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

flow.json コンフィギュレーションファイルへのパスを指定します。-f フラグを複数回使用して複数のコンフィグレーションファイルをマージすることもできます。

Version Check

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

Last updated on Dec 6, 2024 by Alex Ni

翻訳元

---

Previous << Cadence Linter

Flow BlockchainのCadence version1.0ドキュメント (Flow Interaction Templates (FLIX))

Next >> Cadence Boilerplate