Go to Qiita Advent Calendar 2024 Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@abcdefgac153131(Takashi Tahara)

Interaction Templates

Last updated at Posted at 2024-12-01

インタラクションテンプレートは、FLIP-934で確立された概念です。FLIPはこちらでご覧いただけます。

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

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

Overview

Interaction Templates は、インタラクションに関するメタデータのためのフォーマットを構築します。Interaction Templates には以下を含めることができます。

  • 人間が読める国際化(i18n)されたインタラクションに関するメッセージ
  • インタラクションを実行するためのCadence コード
  • 国際化(i18n)された人間が読めるメッセージのような引数に関する情報や、その引数が作用する対象
  • インタラクションを行うコントラクトの依存関係、それらをバージョン固定したもの、およびそれらの依存関係ツリー

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

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

For Wallets

ウォレットは、Interaction Templatesを使用して以下のことを行うことができます。

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

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

Flowは、"Interaction Template Discovery Service"を運営してウォレットがInteraction Templateを照会することができるようにしています。誰でも"Interaction Template Discovery Service"を運営することができ、ウォレットはそれらのいずれかから選んで照会することができます。

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"に関して詳細は、こちらをご覧ください。

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

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

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

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

ウォレットはFCLにアドレスを設定することで信頼する監査機関を指定できます。

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を監査したかどうか、を確認できます。

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が表現するトランザクションが作成された時点から依存関係ツリーと監査対象が何であったかが変更されていないこと、を検証したい場合もあります。
（補足: 監査で信頼できると判定された後にコントラクトが更新されたら、それをインポートしているトランザクションの監査はやり直しが必要になると言っています）

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でユーザーに知らせることもできます。これにより、ユーザーはトランザクションの安全性についてより大きな信頼を持つことができます。

Data Structure

以下は、「$FLOW送金」トランザクションに対応するInteraction Templateの例です。

{
  "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"
            }
          }
        }
      }
    }
  }
}

For Applications

FCL のmutateとqueryは、Interaction Templateを受け入れることができます。
FCL のmutateとqueryは、Interaction Templateを使用して、以下のことが出来ます。

  • ブロックチェーンとのやり取りを実行するための Cadence コードの抽出
  • ブロックチェーンとのやり取りの依存関係コンフィグレーションを抽出（例：スマートコントラクトのインポートアドレスに関する情報）

こちらがmutateで Interaction Template を使用した例です。

import * as fcl from "@onflow/fcl"
import myTransactionTemplate from "./my-transaction-template.template.json"

const txId = await fcl.mutate({
  template: myTransactionTemplate
})

Interaction Templateはqueryと一緒に使うこともできます。

import * as fcl from "@onflow/fcl"
import myScriptTemplate from "./my-script-template.template.json"

const info = await fcl.query({
  template: myScriptTemplate
})

Interaction Templates は離れた場所にあるファイルでも使用できます。

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を読み込むように設定することもできます。

import * as fcl from "@onflow/fcl"

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

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

名称に関する補足:

大変紛らわしいのですが、APIリファレンスにはInteractionのためのtemplate builderという項目があり、Interaction Templateに埋め込むビルダー関数のことかと思ったのですが、違うようです。

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

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

せっかく調査したのでそのAPIリファレンスの各関数もここにまとめます。（Query Builderの関数は同名のグローバル関数があるので、fcl.を外して直接スクリプトやトランザクションのテンプレート内に埋め込むことが出来ます。getAccountの関数はトランザクションで呼び出すとエラーになります。(アカウント情報変更の関数を含むためです)）

Query Builder Description
getAccount アドレスをもとにアカウント情報を取得するインタラクションを返します
getBlock 最新のブロック情報を取得するインタラクションを返します
atBlockHeight 指定したブロック高さのブロックに対する部分的インタラクションを返します
atBlockId 指定したブロックIDのブロックに対する部分的インタラクションを返します
getBlockHeader ブロックのヘッダー情報を取得するインタラクションを返します
getTransactionStatus TransactionStatusObject の形式でトランザクションのステータスを返します
getTransaction トランザクションオブジェクトを返します
Utility Builder Description
arg fcl.args[...] と一緒に使用するユーティリティビルダーで、FCLでサポートされた引数を作成します
args 他のビルダーと組み合わせて使用するユーティリティビルダーで、値とサポートされている型を持つ引数を渡します
Template Builder Description
script Cadenceのスクリプトを実行するのに使用します
transaction Cadence トランザクションを実行するのに使用します

Interaction Templateに関してはData Structureに記載のオブジェクトをウォレットが取得してそのオブジェクトの指示通りに人間が読めるように変換してユーザーに表示するという認識であっているようです。

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

Last updated on Nov 20, 2024 by Chase Fleming

翻訳元

Previous << Installation

Flow BlockchainのCadence version1.0ドキュメント (Clients)

Next >> Proving Ownership of a Flow Account 🚧

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?