Interaction Templates

[Previous << Installation](https://qiita.com/flowcadence/items/fd60e5c15a0626c2adf2)
[Next >> Proving Ownership of a Flow Account](https://qiita.com/flowcadence/items/6032594d047c635939c3)

https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a#reference-2020832ebee1810a325a

> インタラクションテンプレートは、FLIP-934で確立された概念です。FLIPは[こちら](https://github.com/onflow/flips/blob/main/application/20220503-interaction-templates.md)でご覧いただけます。

> この文脈における"Interaction"とは、FLIP-934で確立された上位用語であり、ブロックチェーンと*相互作用する*トランザクションやスクリプトなどを包みます。

(補足: インタラクション = ブロックチェーンとのやり取り)
<h1>Overview</h1>

Interaction Templates は、インタラクションに関するメタデータのためのフォーマットを構築します。Interaction Templates には以下を含めることができます。
* 人間が読める国際化(i18n)されたインタラクションに関するメッセージ
* インタラクションを実行するためのCadence コード
* 国際化(i18n)された人間が読めるメッセージのような引数に関する情報や、その引数が作用する対象
* インタラクションを行うコントラクトの依存関係、それらをバージョン固定したもの、およびそれらの依存関係ツリー

アプリケーションおよびウォレットは、Interaction Templatesおよびそのインタラクションメタデータを使うことができます。


例えば、アプリケーションやウォレットは、ブロックチェーンとのやりとりの実行前に、ユーザーに表示するために、Interaction Templatesから人間が読める国際化(i18n)されたメッセージを抽出することができます。

<h1>For Wallets</h1>

ウォレットは、Interaction Templatesを使用して以下のことを行うことができます。
* 署名時にユーザーに対して、トランザクションに関する人間が読める国際化(i18n)された情報を表示する
* Interaction Templatesが作成された時からその依存関係に変更がないことを確認する
* Interaction TemplatesのAudit(監査)を行うことで、そのトランザクションの正確性と安全性に対する信頼性を得る

署名すべきトランザクションを受け取ると、ウォレットはそれに対応するInteraction Templateを照会することができます。

Flowは、"Interaction Template Discovery Service"を運営してウォレットがInteraction Templateを照会することができるようにしています。誰でも"Interaction Template Discovery Service"を運営することができ、ウォレットはそれらのいずれかから選んで照会することができます。
```ruby
const cadence = cadenceFromTransactionToSign
const network = "mainnet" // "mainnet" | "testnet"

const cadence_base64 = btoa(cadence)

const interactionTemplate = await fetch(
  "https://flix.flow.com/v1/templates/search",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    }
    body: JSON.stringify({
      cadence_base64,
      network
    })
  }
)
```
> 📖 Flowが動かしている"Interaction Template Discovery Service"に関して詳細は、[こちら](https://github.com/onflow/flow-interaction-template-service)をご覧ください。

> ❗️ すべてのトランザクションがInteraction Templateに対応できるわけではありません。ウォレットは、対応するInteraction Templateがない、または発見できないトランザクションの署名をサポートすることが常に推奨されます。

ウォレットは、トランザクションに対応するInteraction Templateを取得したら、そのトランザクションが署名に適した安全なものであること、およびそのInteraction Templateがそのトランザクションに対して正しいことを確認したいと考えるかもしれません。

その場合、ウォレットは、ウォレット自身と外部のInteraction Template監査機関を使ってチェックすることで、Interaction Templateやそのトランザクションが信頼できると自信を持つことができます。Interaction Template監査機関は、Interaction Templateの正確性と安全性を監査する機関です。

> 💡 Interaction Templateの監査機関は誰でもなれます。 ウォレットは、信頼できる監査機関がいる場合は、その監査機関を選ぶことができます。

ウォレットはFCLにアドレスを設定することで信頼する監査機関を指定できます。
```ruby
import * as fcl from "@onflow/fcl"

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

const auditorA_FlowAddress = "0xABC123DEF456"
const auditorB_FlowAddress = "0xFFAA1212DEFF"

await fcl.config().put("flow.auditors", [
  auditorA_FlowAddress,
  auditorB_FlowAddress
])
```
Walletsは、FCLに設定した監査機関が指定のInteraction Templateを監査したかどうか、を確認できます。
```ruby
import * as fcl from "@onflow/fcl"
import myTransactionTemplate from "./my-transaction-template.template.json"

const audits = await fcl.InteractionTemplateUtils
  .getInteractionTemplateAudits({
    template: myTransactionTemplate
  })

/**
 * audits = {
 *   "0xABC123DEF456": true,
 *   "0xFFAA1212DEFF": false
 * }
 ** /
```
Flowチームは、以下の監査機関アカウントを運営しています。
| Flow Team Auditor Accounts | Address |
|:-:|:-:|
| TestNet | 0xf78bfc12d0a786dc |
| MainNet | 0xfd100e39d50a13e6 |

ウォレットが信頼するすべての監査機関が、取得したInteraction Templateを監査したとは限らないため、複数の監査機関を信頼することで、信頼する監査機関の少なくとも1つがInteraction Templateを監査した可能性を高めることができます。

❗️ 監査機関はいつでも監査を取り消せますで、必ずInteraction Template監査ステータスを確認してください。

Flowのスマートコントラクトは変更可能であるため、ウォレットはさらに、Interaction Templateが表現するトランザクションが作成された時点から依存関係ツリーと監査対象が何であったかが変更されていないこと、を検証したい場合もあります。
（補足: 監査で信頼できると判定された後にコントラクトが更新されたら、それをインポートしているトランザクションの監査はやり直しが必要になると言っています）
```ruby
import * as fcl from "@onflow/fcl"
import myTransactionTemplate from "./my-transaction-template.template.json"

const hasDependencyTreeChanged = await fcl.InteractionTemplateUtils
  .verifyDependencyPinsSameAtLatestSealedBlock({
    template: myTransactionTemplate
  })
```
依存関係ツリーが変更された場合、ウォレットはInteraction Template（およびその監査）を無視する選択をすることができます。

ウォレットが信頼する監査機関によってInteraction Templateが十分に監査され、インタラクションが作成されて監査された後に依存関係ツリーに変更がないことが確認された場合、ウォレットはInteraction Templateを、その正確性と安全性についてより高い信頼を持って使用することができます。

ウォレットは、その後トランザクションに関する以下のような、人間が読める情報を表示する決定をする場合があります。
* トランザクションの「タイトル」および「説明」
* トランザクション引数の各々に対する「タイトル」および引数の値

また、ウォレットは、その監査状況をウォレットのUIでユーザーに知らせることもできます。これにより、ユーザーはトランザクションの安全性についてより大きな信頼を持つことができます。

<h1>Data Structure</h1>

以下は、"$FLOW送金"トランザクションに対応するInteraction Templateの例です。
```ruby
{
  "f_type": "InteractionTemplate",
  "f_version": "1.0.0",
  "id": "290b6b6222b2a77b16db896a80ddf29ebd1fa3038c9e6625a933fa213fce51fa",
  "data": {
    "type": "transaction",
    "interface": "",
    "messages": {
      "title": {
        "i18n": {
          "en-US": "Transfer Tokens"
        }
      },
      "description": {
        "i18n": {
          "en-US": "Transfer tokens from one account to another"
        }
      }
    },
    "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}",
    "dependencies": {
      "0xFUNGIBLETOKENADDRESS": {
        "FungibleToken": {
          "mainnet": {
            "address": "0xf233dcee88fe0abe",
            "fq_address": "A.0xf233dcee88fe0abe.FungibleToken",
            "contract": "FungibleToken",
            "pin": "83c9e3d61d3b5ebf24356a9f17b5b57b12d6d56547abc73e05f820a0ae7d9cf5",
            "pin_block_height": 34166296
          },
          "testnet": {
            "address": "0x9a0766d93b6608b7",
            "fq_address": "A.0x9a0766d93b6608b7.FungibleToken",
            "contract": "FungibleToken",
            "pin": "83c9e3d61d3b5ebf24356a9f17b5b57b12d6d56547abc73e05f820a0ae7d9cf5",
            "pin_block_height": 74776482
          }
        }
      }
    },
    "arguments": {
      "amount": {
        "index": 0,
        "type": "UFix64",
        "messages": {
          "title": {
            "i18n": {
              "en-US": "The amount of FLOW tokens to send"
            }
          }
        }
      },
      "to": {
        "index": 1,
        "type": "Address",
        "messages": {
          "title": {
            "i18n": {
              "en-US": "The Flow account the tokens will go to"
            }
          }
        }
      }
    }
  }
}
```

<h1>For Applications</h1>

FCL の`mutate`と`query`は、Interaction Templateを受け入れることができます。
FCL の`mutate`と`query`は、Interaction Templateを使用して、以下のことが出来ます。
* ブロックチェーンとのやり取りを実行するための Cadence コードの抽出
* ブロックチェーンとのやり取りの依存関係コンフィグレーションを抽出（例：スマートコントラクトのインポートアドレスに関する情報）

こちらが`mutate`で Interaction Template を使用した例です。
```ruby
import * as fcl from "@onflow/fcl"
import myTransactionTemplate from "./my-transaction-template.template.json"

const txId = await fcl.mutate({
  template: myTransactionTemplate
})
```
Interaction Templateは`query`と一緒に使うこともできます。
```ruby
import * as fcl from "@onflow/fcl"
import myScriptTemplate from "./my-script-template.template.json"

const info = await fcl.query({
  template: myScriptTemplate
})
```
Interaction Templates は離れた場所にあるファイルでも使用できます。
```ruby
import * as fcl from "@onflow/fcl"

const txId = await fcl.mutate({
  template: "http://interactions.awesome-crypto-project.com/buy-nft"
})

const nftInfo = await fcl.query({
  template: "http://interactions.awesome-crypto-project.com/read-nft",
  args: (arg, t) => [arg("nft-id", t.String)]
})
```
FCLは、テンプレートを使用したトランザクションまたはスクリプトの実行の前に、離れた場所からテンプレートを読み込みます。

> 💡 外部の場所からInteraction Templateを読み込むことで、アプリケーションは常に最新のインタラクションの達成方法を取り込む仕組みが備わります。

FCLはデフォルトでは、http/httpsを通じてのInteraction Templates読み込みをサポートしていますが、FCLは他のさまざまな方法でInteraction Templatesを読み込むように設定することもできます。

```ruby
import * as fcl from "@onflow/fcl"

await fcl.config().put("document.resolver.ipfs", async ({ url }) => {
  /* resolve interaction template from ipfs */
  const jsonTemplate = getDocumentFromIPFS(url)
  return jsonTemplate
})

const txId = await fcl.mutate({
  template: "ipfs://IPFSHASHGOESHERE"
})
```


<h1>名称に関する補足:</h1>

大変紛らわしいのですが、[APIリファレンス](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#builders%E3%82%AA%E3%83%B3%E3%83%81%E3%82%A7%E3%83%BC%E3%83%B3%E6%83%85%E5%A0%B1%E5%8F%96%E5%BE%97)にはInteractionのための**template builder**という項目があり、Interaction Templateに埋め込むビルダー関数のことかと思ったのですが、違うようです。

大変名称が分かりにくいですが、それぞれ以下の意味になります。

* `Interaction Template`はウォレットをより安全にする機能
* `Interaction`のための`template builder`は、スクリプトやトランザクション処理において使えるビルトイン関数

:::note
Interaction Templatesをクライアントとして操作する方法は以下にあります。

https://qiita.com/flowcadence/items/65f173cc69d1eb22e38e

どちらかというと事務的な操作であり、ウォレットが対処するといったコア部分ではない気がしますが、その中に[Resourceのセクション](https://qiita.com/flowcadence/items/65f173cc69d1eb22e38e#resources)があり、その中にウォレットが対処しないといけないようなコードの詳細が書かれています。
:::

<h5>APIリファレンスのビルトイン関数</h5>

せっかく調査したのでそのAPIリファレンスの各関数もここにまとめます。（**Query Builderの関数は同名のグローバル関数があるので、`fcl.`を外して直接スクリプトやトランザクションのテンプレート内に埋め込むことが出来ます。getAccountの関数はトランザクションで呼び出すとエラーになります。**(アカウント情報変更の関数を含むためです)）
| Query Builder | Description |
|:-:|:-:|
| [getAccount](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#getaccount) | アドレスをもとにアカウント情報を取得するインタラクションを返します |
| [getBlock](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#getblock) | 最新のブロック情報を取得するインタラクションを返します |
| [atBlockHeight](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#atblockheight) | 指定したブロック高さのブロックに対する部分的インタラクションを返します |
| [atBlockId](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#atblockid) | 指定したブロックIDのブロックに対する部分的インタラクションを返します |
| [getBlockHeader](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#getblockheader) | ブロックのヘッダー情報を取得するインタラクションを返します |
| [getTransactionStatus](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#gettransactionstatus) | TransactionStatusObject の形式でトランザクションのステータスを返します |
| [getTransaction](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#gettransaction) | トランザクションオブジェクトを返します |

**Builderの定義は[こちら](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#builders)、Interactionの定義は[こちら](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#interaction)にあります**

| [Utility Builder](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#utility-builders) | Description |
|:-:|:-:|
| [arg](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#arg) | `fcl.args[...]` と一緒に使用するユーティリティビルダーで、FCLでサポートされた引数を作成します |
| [args](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#args) | 他のビルダーと組み合わせて使用するユーティリティビルダーで、値とサポートされている型を持つ引数を渡します |


| [Template Builder](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#template-builders) | Description |
|:-:|:-:|
| [script](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#script) | Cadenceのスクリプトを実行するのに使用します |
| [transaction](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#transaction) | Cadence トランザクションを実行するのに使用します |

**(sendとdecodeが必要ない)ショートハンドメソッドとポーリング**
| [Pre-built Interactions](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#pre-built-interactions%E3%82%B7%E3%83%A7%E3%83%BC%E3%83%88%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A1%E3%82%BD%E3%83%83%E3%83%89) | Description |
|:-:|:-:|
| [account](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#account) | 公開アドレスからアカウントの詳細情報を返す |
| [block](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#block) | 最新のブロックを、IDまたは高さで返す |
| [tx](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#tx) |　（ポーリングによる）その後のステータス更新と確定した結果が利用可能になった際に取得する |
| [events](https://qiita.com/flowcadence/items/82c4e2d91df09051b1de#events) | （ポーリングによる）その後の取得可能なイベントがある際に取得できる |

`Interaction Template`に関しては[Data Structure](https://qiita.com/flowcadence/items/e49102ecf2109f9e55bb#data-structure)に記載のオブジェクトをウォレットが取得してそのオブジェクトの指示通りに人間が読めるように変換してユーザーに表示するという認識であっているようです。

（このテンプレートを配布したりするのはAWSやGCPのようなプラットフォーマーが専用のサービスを提供しないと煩雑で厳しいかもしれないですね）

*Last updated on **Nov 20, 2024** by **Chase Fleming***

翻訳元

https://developers.flow.com/tools/clients/fcl-js/interaction-templates

***
<b>[Previous << Installation](https://qiita.com/flowcadence/items/fd60e5c15a0626c2adf2)
</b>

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

<b>[Next >> Proving Ownership of a Flow Account](https://qiita.com/flowcadence/items/6032594d047c635939c3)</b>