Add documentation for project commands #57

psiemens · 2021-02-15T06:51:46Z

Closes #50

Description

Add documentation for the new flow project commands, including the much-anticipated flow project deploy.

For contributor use:

Targeted PR against master branch
Linked to Github issue with discussion and accepted design OR link to spec that describes this work
Code follows the standards mentioned here
Updated relevant documentation
Re-reviewed Files changed in the Github PR explorer
Added appropriate labels

janezpodhostnik

Wow projects! Cant wait to use this!

Was there any thought in adding project support to the vscode flow plugin?

janezpodhostnik · 2021-02-15T15:25:21Z

docs/initialize-project.md

+
+## Example Project Configuration
+
+TODO: add sample project config here


Is this todo meant for later?

@sideninja I saw that you had a pretty good example version of flow.json. Can you add it here?

This is a draft from my docs

title: Deploy contracts with the Flow CLI
sidebar_title: Deploy Contracts
description: How to deploy Cadence contracts using Flow CLI

The Flow CLI provides a command to deploy Cadence contracts on predefined accounts on any network.

flow project deploy-contracts

Example Usage

> flow project deploy-contracts NonFungibleToken -> 0xf8d6e0586b0a20c7 FungibleToken -> 0xf8d6e0586b0a20c7 Kibble -> 0xf8d6e0586b0a20c7 ✅ All contracts deployed successfully

Options

Network

Flag: --network

Valid inputs: "emulator", "testnet", "any"

Default: "emulator"

Network configuration to use for deploy. You can use any network specified in configuration.

Update

Flag: --update

Valid inputs: false, true

Default: false

Use update flag to update existing contracts on the account.

Configuration

Project uses configuration file you can generate by using flow project init command or by hand. After you generate configuration file you must add contracts and accounts you wish to use for deployment.
Bellow is an example configuration file and we will document each configuration option.

{ "contracts": { "NonFungibleToken": "../hungry-kitties/cadence/contracts/NonFungibleToken.cdc", "Kibble": "./cadence/kibble/contracts/Kibble.cdc", "KittyItems": "./cadence/kittyItems/contracts/KittyItems.cdc", "KittyItemsMarket": "./cadence/kittyItemsMarket/contracts/KittyItemsMarket.cdc", "FungibleToken": { "testnet": "0x123", "emulator": "../hungry-kitties/cadence/contracts/NonFungibleToken.cdc" } }, "deploy": { "testnet": { "admin-account": ["NonFungibleToken"], "user-account": ["Kibble", "KittyItems", "KittyItemsMarket"] }, "emulator": { "emulator-account": ["NonFungibleToken", "FungibleToken", "Kibble", "KittyItems", "KittyItemsMarket"] } }, "accounts": { "admin-account": { "address": "0x2244224422", "keys": "22232967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad74b47" }, "user-account": { "address": "0x123123123", "keys": "22232967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad74b47" }, "emulator-account": { "address": "f8d6e0586b0a20c7", "keys": "2eae2f31cb5b756151fa11d82949c634b8f28796a711d7eb1e52cc301edfb3e0", "chain": "flow-emulator" } }, "networks": { "emulator": { "host": "127.0.0.1:3569", "serviceAccount": "emulator-service" }, "testnet": "access.testnet.nodes.onflow.org:9000" } }

Contracts

Contract section defines contract names and their code location or address. We can also use advance format where we can define code location for each network.

Simple format

... "contracts": { "NonFungibleToken": "../hungry-kitties/cadence/contracts/NonFungibleToken.cdc" } ...

Advanced format

... "FungibleToken": { "testnet": "0x123", "emulator": "../hungry-kitties/cadence/contracts/NonFungibleToken.cdc" } ...

Accounts

Account section is used to define account properties such as keys and addresses. Each account must include a name which then gets referenced throught the config file.

Simple format

All we need to define in simple format is address for the account and its private key under keys.

... "accounts": { "admin-account": { "address": "0x2244224422", "keys": "22232967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad74b47" } } ...

Advanced format

Advanced format allows us to define any paramter possible. You can check all the values for paramters (here). Please note we can use service for address in case the account is used on emulator network
as this is a special value that is defined on the run time to the default service address on the emulator network.

... "accounts": { "admin-account": { "address": "service", "chain": "flow-emulator", "keys": [ { "type": "hex", "index": 0, "signatureAlgorithm": "ECDSA_P256", "hashAlgorithm": "SHA3_256", "context": { "privateKey": "1272967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad74b47" } }, { "type": "hex", "index": 1, "signatureAlgorithm": "ECDSA_P256", "hashAlgorithm": "SHA3_256", "context": { "privateKey": "2372967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad74b47" } } ] } } ...

Deploys

Deploys section defines where the deploy-contracts command will deploy specified contracts. This configuration property is like glue that ties together accounts,
contracts and networks all referenced by their name.

Simple format

"deploy": { "emulator": { "emulator-account": ["NonFungibleToken", "FungibleToken", "Kibble", "KittyItems", "KittyItemsMarket"] }, "testnet": { "admin-account": ["NonFungibleToken"], "user-account": ["Kibble", "KittyItems", "KittyItemsMarket"] }, } ...

Networks

Use this section to define networks and their attributes.

Simple format

... "networks": { "emulator": { "host": "127.0.0.1:3569", "serviceAccount": "emulator-service" }, "testnet": "access.testnet.nodes.onflow.org:9000" } ...

We need to update this for the aliases-sources

10thfloor

Nice!

docs/create-accounts.md

docs/deploy-project-contracts.md

docs/execute-scripts.md

docs/generate-keys.md

docs/initialize-project.md

docs/deploy-project-contracts.md

docs/project-contracts.md

devbugging · 2021-02-18T13:01:26Z

docs/deploy-project-contracts.md

+
+In the example above, your `flow.json` file might look something like this:
+
+```json


add ... before and after json config example so we show that is not complete flow.json.

devbugging · 2021-02-18T13:05:17Z

docs/project-contracts.md

+
+⚠️ _Warning: CLI projects are an experimental feature._
+
+## Add a Contract


Should we add also advanced format

docs/project-contracts.md

devbugging · 2021-02-19T13:06:55Z

docs/project-contracts.md

+  },
+  "deploy": {
+    "testnet": {
+      "my-testnet-account": ["Foo", "Bar"]


Should we reference emulator-account in our examples since it is already generated by project init? If a user wants to add more accounts on different networks that should maybe be described in a separate section.

Yes, this is a good idea. Let's follow up with this change

psiemens added the Documentation The issue in documentation, missing docs, invalid docs, outdated docs label Feb 15, 2021

psiemens requested a review from devbugging February 15, 2021 06:51

psiemens requested review from janezpodhostnik, Kay-Zee and turbolent as code owners February 15, 2021 06:51

janezpodhostnik approved these changes Feb 15, 2021

View reviewed changes

Base automatically changed from docs to master February 16, 2021 06:37

10thfloor reviewed Feb 17, 2021

View reviewed changes

devbugging reviewed Feb 18, 2021

View reviewed changes

psiemens and others added 4 commits February 19, 2021 00:34

Add documentation for project commands

7c8761c

added configuration readme

9af0289

Address review feedback from @10thfloor

19c1a65

Temporarily remove config example until we have a new sample

cf6b63d

psiemens force-pushed the project-docs branch from d6c36ee to cf6b63d Compare February 19, 2021 08:34

devbugging reviewed Feb 19, 2021

View reviewed changes

docs/project-contracts.md Outdated Show resolved Hide resolved

devbugging reviewed Feb 19, 2021

View reviewed changes

Update project documentation

31d7406

psiemens force-pushed the project-docs branch from 57b7754 to 31d7406 Compare February 19, 2021 18:59

Rename "deploy" to "deployments"

772ffbb

devbugging approved these changes Feb 19, 2021

View reviewed changes

psiemens merged commit 0cb815a into master Feb 19, 2021

psiemens deleted the project-docs branch February 19, 2021 20:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for project commands #57

Add documentation for project commands #57

psiemens commented Feb 15, 2021 •

edited

Loading

janezpodhostnik left a comment

janezpodhostnik Feb 15, 2021

psiemens Feb 16, 2021

devbugging Feb 16, 2021

devbugging Feb 18, 2021

10thfloor left a comment

devbugging Feb 18, 2021

devbugging Feb 18, 2021

devbugging Feb 19, 2021

psiemens Feb 19, 2021


		## Example Project Configuration

		TODO: add sample project config here


		In the example above, your `flow.json` file might look something like this:

		```json


		⚠️ _Warning: CLI projects are an experimental feature._

		## Add a Contract

Add documentation for project commands #57

Add documentation for project commands #57

Conversation

psiemens commented Feb 15, 2021 • edited Loading

Description

janezpodhostnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This is a draft from my docs

title: Deploy contracts with the Flow CLI sidebar_title: Deploy Contracts description: How to deploy Cadence contracts using Flow CLI

Example Usage

Options

Network

Update

Configuration

Contracts

Simple format

Advanced format

Accounts

Simple format

Advanced format

Deploys

Simple format

Networks

Simple format

Choose a reason for hiding this comment

10thfloor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

psiemens commented Feb 15, 2021 •

edited

Loading

title: Deploy contracts with the Flow CLI
sidebar_title: Deploy Contracts
description: How to deploy Cadence contracts using Flow CLI