From 976b55245251d16b09882606c82a209a09f788f2 Mon Sep 17 00:00:00 2001 From: Tom Haile Date: Wed, 8 Nov 2023 16:00:59 -0600 Subject: [PATCH 1/4] add flix generate to documentation --- docs/tools/flow-cli/flix.md | 77 +++++++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/tools/flow-cli/flix.md b/docs/tools/flow-cli/flix.md index 0176e6da42..58df9b4e67 100644 --- a/docs/tools/flow-cli/flix.md +++ b/docs/tools/flow-cli/flix.md @@ -10,14 +10,15 @@ The Flow CLI provides a `flix` command with a few sub commands `execute` and `pa ```shell >flow flix -execute, package +execute, generate, package Usage: flow flix [command] Available Commands: - execute execute FLIX template with a given id, name, or local filename - package package file for FLIX template fcl-js is default + 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 ``` @@ -60,6 +61,76 @@ Currently, `flix package` command only supports generating FCL (Flow Client Libr flow flix package [flags] ``` +## Generate + +Generate FLIX json file. This command will take in a Cadence file and produce a FLIX json file. There are two ways to provide metadata to populate the FLIX json structure. + - Use `--pre-fill` flag to pass in a pre populated FLIX json structure + - Cadence comment block properties [Cadence Comment Block](https://github.com/onflow/flips/pull/80) + +```shell +# Generate FLIX json file using cadence transaction or script where the cadence uses Cadence Comment block properties +flow flix generate cadence/transactions/update-helloworld.cdc +``` + +Example of Cadence Comment block properties +```cadence +import "HelloWorld" +/* +@f_version 1.0.0 +@lang en-US + +@message title: Update Greeting +@message description: Update the greeting message + +@parameter title greeting: Greeting Message +@parameter description greeting: The new greeting message +*/ +transaction(greeting: String) { + + prepare(acct: AuthAccount) { + log(acct.address) + } + + execute { + HelloWorld.updateGreeting(newGreeting: greeting) + } +} +``` + + +```shell +# Generate FLIX json file using cadence transaction or script passing in a pre filled FLIX json file. The json file will get filled out by the `flow flix generate` command +flow flix generate cadence/scripts/read-helloworld.cdc --pre-fill cadence/templates/read-helloworld.prefill.json +``` +Example of prefilled FLIX json file +```json +{ + "f_type": "InteractionTemplate", + "f_version": "1.0.0", + "id": "", + "data": { + "type": "script", + "interface": "", + "messages": { + "title": { + "i18n": { + "en-US": "Get Greeting" + } + }, + "description": { + "i18n": { + "en-US": "Get the greeting from the HelloWorld class" + } + } + }, + "cadence": "", + "dependencies": {}, + "arguments": {} + } +} + +``` + ## Package Queries can be a FLIX `id`, `name`, or `path` to a local FLIX file. This command leverages [FCL](../clients/fcl-js/) which will execute FLIX cadence code. From 310ca4eab885216d108a1eedc9ffa41a2277ce36 Mon Sep 17 00:00:00 2001 From: Tom Haile Date: Wed, 8 Nov 2023 16:07:34 -0600 Subject: [PATCH 2/4] update to add generate output examples --- docs/tools/flow-cli/flix.md | 64 +++++++++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 9 deletions(-) diff --git a/docs/tools/flow-cli/flix.md b/docs/tools/flow-cli/flix.md index 58df9b4e67..7854668b84 100644 --- a/docs/tools/flow-cli/flix.md +++ b/docs/tools/flow-cli/flix.md @@ -61,15 +61,17 @@ Currently, `flix package` command only supports generating FCL (Flow Client Libr flow flix package [flags] ``` -## Generate +### Generate Generate FLIX json file. This command will take in a Cadence file and produce a FLIX json file. There are two ways to provide metadata to populate the FLIX json structure. - Use `--pre-fill` flag to pass in a pre populated FLIX json structure - - Cadence comment block properties [Cadence Comment Block](https://github.com/onflow/flips/pull/80) + - Cadence comment block properties [FLIP - Interaction Template Cadence Doc](https://github.com/onflow/flips/pull/80) + +### Generate Usage ```shell # Generate FLIX json file using cadence transaction or script where the cadence uses Cadence Comment block properties -flow flix generate cadence/transactions/update-helloworld.cdc +flow flix generate cadence/transactions/update-helloworld.cdc --save cadence/templates/update-helloworld.template.json ``` Example of Cadence Comment block properties @@ -100,7 +102,7 @@ transaction(greeting: String) { ```shell # Generate FLIX json file using cadence transaction or script passing in a pre filled FLIX json file. The json file will get filled out by the `flow flix generate` command -flow flix generate cadence/scripts/read-helloworld.cdc --pre-fill cadence/templates/read-helloworld.prefill.json +flow flix generate cadence/scripts/read-helloworld.cdc --pre-fill cadence/templates/read-helloworld.prefill.json --save cadence/templates/read-helloworld.template.json ``` Example of prefilled FLIX json file ```json @@ -131,7 +133,49 @@ Example of prefilled FLIX json file ``` -## Package +### Example Generate Output + +```json +{ + "f_type": "InteractionTemplate", + "f_version": "1.0.0", + "id": "ae9c0b156742eeb6bb1ae0b7b8ea94cfc21498d613e933171aa1e4f4a9ae6ea3", + "data": { + "type": "script", + "interface": "", + "messages": { + "title": { + "i18n": { + "en-US": "Read Greeting" + } + }, + "description": { + "i18n": { + "en-US": "Read the greeting from the HelloWorld class" + } + } + }, + "cadence": "import HelloWorld from 0xHelloWorld\n/*\n@f_version 1.0.0\n@lang en-US\n@message title: Read Greeting\n@message description: Read the greeting from the HelloWorld class\n\n@return String\n */\npub fun main(): String {\n return HelloWorld.greeting\n}\n", + "dependencies": { + "0xHelloWorld": { + "HelloWorld": { + "testnet": { + "address": "0xa58395c2f736c46e", + "fq_address": "A.a58395c2f736c46e.HelloWorld", + "contract": "HelloWorld", + "pin": "82d8fb62ec356884316c28388630b9acb6ba5027d566efe0d2adff2c6e74b4dc", + "pin_block_height": 131038531 + } + } + } + }, + "arguments": {} + } +} + +``` + +### Package Queries can be a FLIX `id`, `name`, or `path` to a local FLIX file. This command leverages [FCL](../clients/fcl-js/) which will execute FLIX cadence code. @@ -185,10 +229,6 @@ export async function transferTokens({amount, to}) { } ``` - -SOON: `flix generate` will generate FLIX json files using FLIX specific properties in comment blocks directly in Cadence code, [FLIP - Interaction Template Cadence Doc](https://github.com/onflow/flips/pull/80) - - ## Resources @@ -217,6 +257,12 @@ Arguments passed to the Cadence script in the Cadence JSON format. Cadence JSON format contains `type` and `value` keys and is [documented here](../../cadence/json-cadence-spec.md). +## Pre Fill + +- Flag: `--pre-fill` +- Valid inputs: a json file in the FLIX json structure [FLIX json format](https://github.com/onflow/flips/blob/main/application/20220503-interaction-templates.md) + + ## Block Height - Flag: `--block-height` From 62cc1a358d34c645bf3c9a0e3c42242b4e3fa156 Mon Sep 17 00:00:00 2001 From: Tom Haile Date: Wed, 8 Nov 2023 16:11:02 -0600 Subject: [PATCH 3/4] add new execute | package using url to remote flix json file --- docs/tools/flow-cli/flix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tools/flow-cli/flix.md b/docs/tools/flow-cli/flix.md index 7854668b84..607767f04c 100644 --- a/docs/tools/flow-cli/flix.md +++ b/docs/tools/flow-cli/flix.md @@ -31,7 +31,7 @@ The Flow CLI provides a `flix` command to `execute` FLIX. The Cadence being exec flow flix execute [ ...] [flags] ``` -Queries can be a FLIX `id`, `name`, or `path` to a local FLIX file. +Queries can be a FLIX `id`, `name`, `url` or `path` to a local FLIX file. ### Execute Usage @@ -177,7 +177,7 @@ Example of prefilled FLIX json file ### Package -Queries can be a FLIX `id`, `name`, or `path` to a local FLIX file. This command leverages [FCL](../clients/fcl-js/) which will execute FLIX cadence code. +Queries can be a FLIX `id`, `name`, `url` or `path` to a local FLIX file. This command leverages [FCL](../clients/fcl-js/) which will execute FLIX cadence code. ### Package Usage From 637738d279ddf45da32640b3b27b367eb4327402 Mon Sep 17 00:00:00 2001 From: Tom Haile Date: Tue, 14 Nov 2023 11:45:37 -0600 Subject: [PATCH 4/4] update examples of using prefill and output --- docs/tools/flow-cli/flix.md | 111 +++++++++++++++++++++++++++--------- 1 file changed, 84 insertions(+), 27 deletions(-) diff --git a/docs/tools/flow-cli/flix.md b/docs/tools/flow-cli/flix.md index 607767f04c..0d5899640b 100644 --- a/docs/tools/flow-cli/flix.md +++ b/docs/tools/flow-cli/flix.md @@ -65,28 +65,17 @@ flow flix package [flags] Generate FLIX json file. This command will take in a Cadence file and produce a FLIX json file. There are two ways to provide metadata to populate the FLIX json structure. - Use `--pre-fill` flag to pass in a pre populated FLIX json structure - - Cadence comment block properties [FLIP - Interaction Template Cadence Doc](https://github.com/onflow/flips/pull/80) ### Generate Usage ```shell -# Generate FLIX json file using cadence transaction or script where the cadence uses Cadence Comment block properties +# 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 ``` -Example of Cadence Comment block properties +Example of Cadence simple, no metadata associated ```cadence import "HelloWorld" -/* -@f_version 1.0.0 -@lang en-US - -@message title: Update Greeting -@message description: Update the greeting message - -@parameter title greeting: Greeting Message -@parameter description greeting: The new greeting message -*/ transaction(greeting: String) { prepare(acct: AuthAccount) { @@ -97,65 +86,115 @@ transaction(greeting: String) { HelloWorld.updateGreeting(newGreeting: greeting) } } -``` +``` +Resulting json when no prefill json is used +```json +{ + "f_type": "InteractionTemplate", + "f_version": "1.0.0", + "id": "f5873ad5c845458619f2781e085a71d03ed9e8685ca6e1cfff8e139645227360", + "data": { + "type": "transaction", + "interface": "", + "messages": {}, + "cadence": "import HelloWorld from 0xHelloWorld\ntransaction(greeting: String) {\n\n prepare(acct: AuthAccount) {\n log(acct.address)\n }\n\n execute {\n HelloWorld.updateGreeting(newGreeting: greeting)\n }\n}\n", + "dependencies": { + "0xHelloWorld": { + "HelloWorld": { + "testnet": { + "address": "0xa58395c2f736c46e", + "fq_address": "A.a58395c2f736c46e.HelloWorld", + "contract": "HelloWorld", + "pin": "82d8fb62ec356884316c28388630b9acb6ba5027d566efe0d2adff2c6e74b4dc", + "pin_block_height": 132414699 + } + } + } + }, + "arguments": { + "greeting": { + "index": 0, + "type": "String", + "messages": {}, + "balance": "" + } + } + } +} +``` ```shell # Generate FLIX json file using cadence transaction or script passing in a pre filled FLIX json file. The json file will get filled out by the `flow flix generate` command flow flix generate cadence/scripts/read-helloworld.cdc --pre-fill cadence/templates/read-helloworld.prefill.json --save cadence/templates/read-helloworld.template.json ``` -Example of prefilled FLIX json file +Example of json prefill file with message metadata ```json { "f_type": "InteractionTemplate", "f_version": "1.0.0", "id": "", "data": { - "type": "script", + "type": "transaction", "interface": "", "messages": { "title": { "i18n": { - "en-US": "Get Greeting" + "en-US": "Update Greeting" } }, "description": { "i18n": { - "en-US": "Get the greeting from the HelloWorld class" + "en-US": "Update greeting of the HelloWorld smart contract" } } }, "cadence": "", "dependencies": {}, - "arguments": {} + "arguments": { + "greeting": { + "messages": { + "title": { + "i18n": { + "en-US": "Greeting" + } + }, + "description": { + "i18n": { + "en-US": "HelloWorld contract greeting" + } + } + } + } + } } } ``` -### Example Generate Output +Example of generated output using prefilled json ```json { "f_type": "InteractionTemplate", "f_version": "1.0.0", - "id": "ae9c0b156742eeb6bb1ae0b7b8ea94cfc21498d613e933171aa1e4f4a9ae6ea3", + "id": "7238aed3ce8588ba3603d7a0ad79bf3aa1f7848618a61ae93d6865aff15387b2", "data": { - "type": "script", + "type": "transaction", "interface": "", "messages": { "title": { "i18n": { - "en-US": "Read Greeting" + "en-US": "Update Greeting" } }, "description": { "i18n": { - "en-US": "Read the greeting from the HelloWorld class" + "en-US": "Update greeting of the HelloWorld smart contract" } } }, - "cadence": "import HelloWorld from 0xHelloWorld\n/*\n@f_version 1.0.0\n@lang en-US\n@message title: Read Greeting\n@message description: Read the greeting from the HelloWorld class\n\n@return String\n */\npub fun main(): String {\n return HelloWorld.greeting\n}\n", + "cadence": "import HelloWorld from 0xHelloWorld\ntransaction(greeting: String) {\n\n prepare(acct: AuthAccount) {\n log(acct.address)\n }\n\n execute {\n HelloWorld.updateGreeting(newGreeting: greeting)\n }\n}\n", "dependencies": { "0xHelloWorld": { "HelloWorld": { @@ -164,12 +203,30 @@ Example of prefilled FLIX json file "fq_address": "A.a58395c2f736c46e.HelloWorld", "contract": "HelloWorld", "pin": "82d8fb62ec356884316c28388630b9acb6ba5027d566efe0d2adff2c6e74b4dc", - "pin_block_height": 131038531 + "pin_block_height": 132414700 } } } }, - "arguments": {} + "arguments": { + "greeting": { + "index": 0, + "type": "String", + "messages": { + "title": { + "i18n": { + "en-US": "Greeting" + } + }, + "description": { + "i18n": { + "en-US": "HelloWorld contract greeting" + } + } + }, + "balance": "" + } + } } }