Flow Interaction Templates (FLIX)

[Previous << Cadence Linter](https://qiita.com/flowcadence/items/25a7923f97d6138062a4)
[Next >> Cadence Boilerplate](https://qiita.com/flowcadence/items/3f9a3b3f175fdd48cf91)

https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a#flow-cli-と-fcl

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

<h1>Introduction</h1>

Flow CLIは`flix`コマンドと、そのサブコマンドの`execute`と`package`を提供しています。Flow Interaction Templates ([FLIX](https://github.com/onflow/flips/blob/main/application/20230330-interaction-templates-1.1.0.md)に慣れ親しんでください。FLIXは、Cadenceスクリプトやトランザクション、メタデータを、ツールやウォレットで利用可能な形で、配布するためのスタンダードです。FLIXは、エコシステム内の監査機関によって、正確性と安全性を監査することができます。
```ruby
>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
```

<h3>Execute</h3>

Flow CLIは、FLIXを`execute`する`flix`コマンドを提供しています。FLIXで実行されるCadenceは、トランザクションまたはスクリプトです。
```ruby
flow flix execute <query> [<argument> <argument>...] [flags]
```
:::note warn
WARNING
FLIXテンプレートは、テストネットおよび/またはメインネットのみをサポートしている場合があります。一般的に、エミュレータはサポートされていません。もし、FLIXテンプレートがスマートコントラクトの依存関係に依存している場合、このようなケースになる可能性があります。
:::
クエリ(query)は、FLIXの`id`、 `name`、 `url`、またはローカルFLIXファイルへの`path`がなり得ます。
<h3>Execute Usage</h3>

```ruby
# Execute a FLIX transaction by name on Testnet
flow flix execute transfer-flow 5.0 "0x123" --network testnet --signer "testnet-account"
```
```ruby
# Execute a FLIX script by id on Testnet
flow flix execute bd10ab0bf472e6b58ecc0398e9b3d1bd58a4205f14a7099c52c0640d9589295f --network testnet
```
```ruby
# 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します。

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

<h3>Generate</h3>

FLIX jsonファイルを生成します。このコマンドはCadenceファイルを受け取り、FLIX jsonファイルを生成します。FLIX json構造にメタデータを埋め込むには、2つの方法があります。
* `--pre-fill`フラグを使用して、事前に埋め込まれたFLIX json構造を渡します
* `--exclude-networks`フラグを使用して、FLIXテンプレートを生成する際に除外するネットワークを指定します。例：`--exclude-networks testnet,mainnet`

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

<h3>Generate Usage</h3>

```ruby
# 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の例
```ruby
import "HelloWorld"
access(all) fun main(): String {
  return HelloWorld.greeting
}
```

<h3>Cadence Doc Pragma:</h3>

スクリプトやトランザクションに対してメタデータを設定するには、プラグマ(pragma)を使用することをお勧めします。より詳しくは、[Cadence Doc Pragma FLIP](https://github.com/onflow/flips/blob/main/application/20230406-interaction-template-cadence-doc.md)をご覧ください。

pragmaは"実用的な情報(pragmatic information)"の略語であり、プロセッサに情報を伝える特別な指示です（この場合、FLIXを生成しているユーティリティ）。
```ruby
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)
  }
}
```
:::note
INFO
Cadence v0.42.7は、追加のFlIXユーティリティがFLIXを生成する際に使用できるCadenceプラグマ機能をサポートします。それはパラメータ"title"と"description"をサポートします。
:::
生成されたjsonメタデータは、Cadence Doc Pragmaから抽出されます。
```ruby
{
    "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`コマンドを使用します。
```ruby
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ファイルはシンプルになりますが、メタデータが付随しません。
```ruby
import "HelloWorld"
access(all) fun main(): String {
  return HelloWorld.greeting
}
```
メッセージメタデータを含むjson事前埋め込みファイルの例：
```ruby
{
    "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ファイル：
```ruby
{
    "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
    }
}
```

<h3>Package</h3>

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

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

<h3>Package Usage</h3>

```ruby
# 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
```
```ruby
# 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
```
```ruby
# Generate package code using local template file to save in a local file 
flow flix package ./multiply.template.json --save ./multiply.js
```
```ruby
# 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
```

<h3>Example Package Output</h3>

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

/**
    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
}
```
```ruby
# Generate TypeScript version of package file 
flow flix package https://flix.flow.com/v1/templates?name=transfer-flow --lang ts
```
```ruby

/**
    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
}
```

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

<h1>Resources</h1>

FLIXについてさらに詳しく知りたい場合は、[read the FLIP](https://github.com/onflow/flips/blob/main/application/20230330-interaction-templates-1.1.0.md)を参照してください。

すべてのテンプレートの一覧については、[FLIXテンプレートリポジトリ](https://github.com/onflow/flow-interaction-template-service/tree/master/templates)をご覧ください。

FLIXを生成するには、[FLIX CLI readme](https://github.com/onflow/flow-interaction-template-tools/tree/master/cli)を参照してください。

<h1>Arguments</h1>

* Name: `argument`
* Valid input: valid [FLIX](https://github.com/onflow/flips/blob/main/application/20230330-interaction-templates-1.1.0.md)

ソースコード内の対応する型に一致した入力引数値を、同じ順序で渡します。FLIX実行スクリプトを次のようにして実行することで、オプショナル引数に`nil`値を渡すことができます: `flow flix execute template.json nil`

<h1>Flags</h1>
<h3>Arguments JSON</h3>

* 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`のキーが含まれ、[こちらで説明](https://qiita.com/flowcadence/items/24135a1ea2f755e7fd19)されています。
<h3>Pre Fill</h3>

* Flag: `--pre-fill`
* Valid inputs: a json file in the FLIX json structure [FLIX json format](https://github.com/onflow/flips/blob/main/application/20230330-interaction-templates-1.1.0.md)

<h3>Block Height</h3>

* Flag: `--block-height`
* Valid inputs: a block height number

<h3>Block ID</h3>

* Flag: `--block-id`
* Valid inputs: a block ID

<h3>Signer</h3>

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

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

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

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

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

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

<h3>Authorizer</h3>

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

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


<h3>Gas Limit</h3>

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

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

<h3>Host</h3>

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

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

<h3>Network Key</h3>

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

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

<h3>Network</h3>

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

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

<h3>Filter</h3>

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

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

<h3>Output</h3>

* Flag: `--output`
* Short Flag: `-o`
* Valid inputs: `json`, `inline`

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

<h3>Save</h3>

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

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

<h3>Log</h3>

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

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

<h3>Configuration</h3>

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

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

<h3>Version Check</h3>

* Flag: `--skip-version-check`
* Default: `false`

*Last updated on **Dec 6, 2024** by **Alex Ni***

翻訳元

https://developers.flow.com/tools/flow-cli/flix

***
<b>[Previous << Cadence Linter](https://qiita.com/flowcadence/items/25a7923f97d6138062a4)
</b>

[Flow blockchain / Cadence version1.0ドキュメント](https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a) (Flow Interaction Templates (FLIX))

<b>[Next >> Cadence Boilerplate](https://qiita.com/flowcadence/items/3f9a3b3f175fdd48cf91)</b>