diff --git a/docs/blockchain-development-tutorials/cadence/cadence-advantages/compose-with-cadence-transactions.md b/docs/blockchain-development-tutorials/cadence/cadence-advantages/compose-with-cadence-transactions.md index aaa23ca7ae..7a6a8d372b 100644 --- a/docs/blockchain-development-tutorials/cadence/cadence-advantages/compose-with-cadence-transactions.md +++ b/docs/blockchain-development-tutorials/cadence/cadence-advantages/compose-with-cadence-transactions.md @@ -434,6 +434,6 @@ This approach gives you the freedom to build complex application logic that comp [transaction]: https://cadence-lang.org/docs/language/transactions [account commands]: ../../../build/tools/flow-cli/commands#account-management [Send the transaction]: ../../../build/tools/flow-cli/commands#send-transaction -[emulator]: ../../../build/tools/flow-cli/deployment/start-emulator +[emulator]: ../../../build/tools/emulator/index.md [MintExampleNFT transaction]: https://github.com/mfbz/flow-nft-tester/blob/main/cadence/transactions/MintExampleNFT.cdc [testnet Flowscan]: https://testnet.flowscan.io/ diff --git a/docs/build/cadence/advanced-concepts/flix.md b/docs/build/cadence/advanced-concepts/flix.md index 360e587f12..0bf8a853eb 100644 --- a/docs/build/cadence/advanced-concepts/flix.md +++ b/docs/build/cadence/advanced-concepts/flix.md @@ -11,7 +11,7 @@ keywords: - FCL - interaction templates - template service -sidebar_position: 3 +sidebar_position: 10 --- # FLIX (Flow Interaction Templates) diff --git a/docs/build/cadence/smart-contracts/deploying.md b/docs/build/cadence/smart-contracts/deploying.md index 36988d13e4..c62321b18a 100644 --- a/docs/build/cadence/smart-contracts/deploying.md +++ b/docs/build/cadence/smart-contracts/deploying.md @@ -1,7 +1,7 @@ --- title: Deploying Contracts sidebar_label: Deploying Contracts -description: Learn how to deploy and update smart contracts on Flow Mainnet and Testnet. Understand account creation, key management, deployment best practices, and network sporks. +description: Learn how to deploy and update smart contracts on Flow Mainnet and Testnet. Understand account creation, key management, and deployment best practices. sidebar_position: 3 sidebar_custom_props: icon: πŸ₯‡ @@ -23,98 +23,338 @@ keywords: - Flow deployment --- -In order to deploy your smart contracts to the mainnet, you need a funded account. If you want to get started on Testnet, look below for information on how to get started. +# Deploying Contracts - -Make sure you handle your mainnet account keys appropriately. Using a Key Management Service is the best practice. - +Deploying smart contracts to Flow's networks is the final step in bringing your blockchain application to life. This guide covers everything you need to know to deploy your Cadence contracts to both Flow Testnet and Mainnet, from account creation to contract updates. -### Creating an Account +## What You'll Learn -There are two simple methods of creating an account on testnet. **Interactive** and **Manual**, both use the Flow CLI. On mainnet you will have to fund your newly created account, there is no faucet. -Make sure to install the Flow CLI. [Flow CLI](../../../build/tools/flow-cli/accounts/create-accounts.md) has a interactive mode for generating keys. +After completing this guide, you'll be able to: - -Anyone can deploy and update contracts on mainnet. Audits are encouraged but not mandatory to deploying contracts to mainnet. Take every precauction to reduce issues and protect users. - +- **Create and fund accounts** on Flow Testnet and Mainnet +- **Deploy contracts** using Flow CLI with proper configuration +- **Update existing contracts** while preserving their addresses +- **Understand the differences** between testnet and mainnet deployment +- **Follow security best practices** for production deployments -### Create and deploy a mainnet project +## Prerequisites -The tool of choice is Flow CLI, there are quickstarts and guides that use Flow CLI, [Getting Started](../../../blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction) +Before deploying contracts, make sure you have: -- It is highly encouraged to test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow any additional guidelines set out here: [Smart Contract Testing Guidelines](./testing.md). -- Follow the Flow CLI instructions to [Create a Project](../../../build/tools/flow-cli/index.md). You have the Flow CLI installed and ran `flow init` in your project folder and generating a `flow.json` file -- Mainnet account: You completed the mainnet account setup, (see above) and have your key pair and mainnet address ready. -- [Deploy your project](../../../build/tools/flow-cli/deployment/deploy-project-contracts.md), notice that your account now has contracts deployed on mainnet. -- [Deploy a contract](../../../build/tools/flow-cli/accounts/account-add-contract.md) to mainnet. You can deploy contracts individually using the `account-add-contract` command. +- **Flow CLI installed** and configured +- **A Flow project** with contracts ready for deployment +- **Basic understanding** of Cadence smart contracts +- **Completed testing** of your contracts locally - -All your contract deployment addresses are stored in `flow.json`. Mainnet, Testnet and local (emulator) are stored as well. - +## Deployment Workflow + +The recommended deployment workflow follows this progression: + +1. **Emulator Deployment** - Deploy and test your contracts locally (free, instant) +2. **Testnet Deployment** - Deploy and test your contracts on Flow Testnet (free) +3. **Mainnet Deployment** - Deploy to Flow Mainnet once testing is complete (costs FLOW tokens) +4. **Contract Updates** - Update contracts as needed using the update command + +This approach ensures your contracts work correctly before committing real resources to mainnet deployment. + +## Deploy to Emulator + +The Flow Emulator is your local development environment where you can deploy and test contracts instantly without any network costs or delays. This is the first step in your deployment journey. + +### Start the Emulator + +First, start the [Flow Emulator]. In a second terminal: + +```zsh +flow emulator start +``` + +### Create an Emulator Account + +Create a local account for testing: + +```zsh +flow accounts create --network emulator +``` + +When prompted: + +1. **Account name**: Enter `emulator-account` +2. Select `emulator` as the network when prompted + +This creates a new account on the emulator and adds it to your `flow.json` configuration. + +### Configure Emulator Deployment + +Update your `flow.json` to include emulator deployment configuration: + +```zsh +flow config add deployment +``` + +Follow the prompts: + +1. **Network**: `emulator` +2. **Account**: `emulator-account` +3. **Contract**: `YourContract` +4. **Deploy more contracts**: `no` (or `yes` if you have multiple contracts) + +Your `flow.json` will now include an emulator deployment section: + +```json +{ + "deployments": { + "emulator": { + "emulator-account": ["YourContract"] + } + } +} +``` + +### Deploy Contract to Emulator + +Deploy your contract to the local emulator: + +```zsh +flow project deploy --network emulator +``` + +:::warning + +You cannot deploy the same contract to multiple accounts on the same network with one deployment command. If you attempt to do so, you will see: + +❌ Command Error: the same contract cannot be deployed to multiple accounts on the same network + +Edit `flow.json` to remove the duplicate. + +::: + +You will see output similar to: + +```zsh +Deploying 1 contracts for accounts: emulator-account + +YourContract -> 0xf8d6e0586b0a20c7 (contract deployed successfully) + +πŸŽ‰ All contracts deployed successfully +``` + +### Test Your Emulator Deployment + +Verify your contract works by running scripts and transactions: + +```zsh +# Run a script to read contract state +flow scripts execute cadence/scripts/YourScript.cdc --network emulator + +# Send a transaction to interact with your contract +flow transactions send cadence/transactions/YourTransaction.cdc --network emulator --signer emulator-account +``` + +:::info + +The emulator provides instant feedback and is perfect for rapid development and testing. All transactions are free and execute immediately. -### Deploy updated contracts on mainnet +::: -Contracts can be updated and retain the contract address. You can use the [Flow CLI contract update command](../../../build/tools/flow-cli/accounts/account-update-contract.md) to re-deploy an updated version of your contract: +## Deploy to Testnet - -If you see `Error Code: 1103`, your new account does not have enough funds to complete the transaction. Make sure you have enough FLOW and your account is set up correctly, check [Flowdiver](https://flowdiver.io/) to verify. - +For a more complete quickstart, visit the [Getting Started] guide. -Once all your contracts are deployed, you can visit [flow-view-source](https://flow-view-source.com/) or run the [Flow CLI get account command](../../../build/tools/flow-cli/accounts/get-accounts.md) to confirm the deployment. +- You should test your contracts, transactions and scripts on Testnet, have strong smart contract test coverage and follow the additional guidelines set out here: [Smart Contract Testing Guidelines]. +- Use `flow init` to [Create a Project] if you need one to practice deployment with. -### Sporks +### Create a Testnet Account -Currently, **historical event data is not migrated between sporks,** so you'll need to design your application with this in mind. We recognize the usefulness of historical event data and plan on adding a means of accessing it in the near future. Past spork transactional data is available, [See Previous Spork Access Node Info](../../../protocol/node-ops/node-operation/past-upgrades) +First, you'll need a testnet account to deploy your contracts. Create one with: -More Information on [Sporks](../../../protocol/node-ops/node-operation/network-upgrade) +```zsh +flow accounts create --network testnet +``` -### Testnet +:::info -The Flow test network, known as Flow Testnet, exists to help developers test their software and smart contracts against a live network. It's also used as a means of releasing and testing new protocol and smart contract features before they are integrated into Flow's main network (Mainnet). +For security reasons, Flow Cadence does not allow accounts to have the same address on testnet, mainnet, and/or the emulator. -When the Flow protocol is updated or a new version of Cadence is released, those updates will always be made available on the [Flow Emulator](../../../build/tools/emulator) _before_ they're integrated into Flow Testnet or Flow Mainnet. +:::: -## Getting Started on Testnet +When prompted: -If you need to create a flow.json file to store information about accounts and contracts use the `flow init` command to create a project - -To create accounts and generate keys, make sure to install [Flow CLI](../../../build/tools/flow-cli/install). Flow CLI provides convenient functions to simplifies interacting with the blockchain. - +1. **Account name**: Enter `testnet-account` +2. Select `testnet` as the network when prompted -### Creating an Account +This creates a new account on testnet and adds it to your `flow.json` configuration. It also saves the private key for the new account in `.pkey` and uses this file to import the key because `flow.json` will be visible in the repo. -There is a simple Flow CLI command to run to create an account. `flow accounts create` command will create a new account and generate a key pair then add the account to your flow.json. The command will try and You can also use the [Testnet Faucet](https://faucet.flow.com/fund-account) to create and fund an account. +:::danger -More information about [Flow CLI](../../../build/tools/flow-cli/accounts/create-accounts) and creating accounts. +As with any other blockchain network, **anyone** with access to the private key for an account can access that account at any time without you knowing. -### Creating and deploying a Project +::: -Flow CLI can be used to create a Cadence project and stay organized, [Flow CLI: Create a project](../../../build/tools/flow-cli). This will make deployment much easiler and help with the iterative development process. +### Fund Your Testnet Account -After you have a project created and want to deploy your Cadence; contracts, transactions and scripts. -`flow accounts add-contract --signer --network testnet` will deploy your contract to testnet. -More information on how to use Flow CLI to [deploy](../../../build/tools/flow-cli/deployment/deploy-project-contracts.md). +To deploy contracts and send transactions on testnet, you need FLOW tokens. Flow provides a faucet service to get free testnet tokens. -Make sure Flow project was initialized in the previous step and the `flow.json` is present. +```zsh +flow accounts fund testnet-account +``` -### Making Use of Core Contracts +This will open the faucet in your browser. You can also navigate there manually. -Flow Testnet comes with some useful contracts already deployed, called **core contracts.** More information and import addresses for the [core contracts](../core-contracts/index.md). +1. Visit the [Testnet Faucet] +2. Enter your testnet account address +3. Complete any required verification (captcha, etc.) +4. Request tokens (you'll receive 100000 testnet FLOW tokens) -Once your accounts are set up and you're ready to develop, you can look over [some code examples from the Flow Go SDK](https://github.com/onflow/flow-go-sdk/tree/master/examples). +Check your account balance: -### Breaking Changes +```zsh +flow accounts list +``` -The Flow blockchain is improved continuously and thus version updates to Cadence, Flow node software, and the Flow SDKs will contain important updates as well as breaking changes. +You will see your account details with a balance of FLOW tokens. -You should anticipate future updates and join the community ([Forum](https://forum.flow.com/) or [Discord](https://discord.com/invite/J6fFnh2xx6)) to stay tuned on important announcements. Notices and guidelines for changes will be provided as early as possible. +### Configure Testnet Deployment -### Testnet Sporking +Update your `flow.json` to include testnet deployment configuration: -"Sporking" (soft forking) is the process of upgrading the Flow network node software and migrating the chain state from one version to another. +```zsh +flow config add deployment +``` -Currently, **historical event data is not migrated between sporks.** You'll need to design your application with this in mind. We recognize the usefulness of historical event data and plan on adding a means of accessing it in the near future. Only one previous spork data is available through old Access Node. +Follow the prompts: + +1. **Network**: `testnet` +2. **Account**: `testnet-account` +3. **Contract**: `YourContract` +4. **Deploy more contracts**: `no` (or `yes` if you have multiple contracts) + +Your `flow.json` will now include a testnet deployment section: + +```json +{ + "deployments": { + "testnet": { + "testnet-account": ["YourContract"] + } + } +} +``` + +### Deploy Contract to Testnet + +Deploy your contract to the public testnet: + +```zsh +flow project deploy --network testnet +``` + +You will see output similar to: + +```zsh +Deploying 1 contracts for accounts: testnet-account + +YourContract -> 0x9942a81bc6c3c5b7 (contract deployed successfully) + +πŸŽ‰ All contracts deployed successfully +``` + +## Deploy to Mainnet + +Once you've successfully tested your contracts on testnet, you can deploy to mainnet. You'll need a mainnet account with real FLOW tokens. + +### Create a Mainnet Account + +For mainnet, you'll need to acquire FLOW tokens through exchanges or other means, as there's no faucet. + +```zsh +flow accounts create --network mainnet +``` + +When prompted: + +1. **Account name**: Enter `mainnet-account` +2. **Select "Mainnet" Network** + +### Acquire FLOW Tokens + +You can purchase FLOW tokens from major exchanges. Make sure your mainnet account has sufficient FLOW tokens to cover deployment costs. Flow is a very efficient network, so even 1.0 FLOW is sufficient to deploy large numbers of contracts. + +### Configure Mainnet Deployment + +Add mainnet deployment configuration to your `flow.json`: + +```zsh +flow config add deployment --network mainnet +``` + +Follow the prompts: + +1. **Network**: `mainnet` +2. **Account**: `mainnet-account` +3. **Contract**: `YourContract` +4. **Deploy more contracts**: `no` (or `yes` if you have multiple contracts) + +Your `flow.json` should now include mainnet configuration: + +```json +{ + "deployments": { + "mainnet": { + "mainnet-account": ["YourContract"] + } + } +} +``` + +### Deploy to Mainnet + +Deploy your contracts to mainnet: + +```zsh +flow project deploy --network mainnet +``` + +:::warning + +This deployment costs (a relatively small amount of) real FLOW tokens and cannot be undone. You can however redeploy your contracts to update them, or delete them. + +::: + +You should see output similar to: + +```zsh +Deploying 1 contracts for accounts: mainnet-account + +YourContract -> 0xABC123DEF456789 (contract deployed successfully) + +πŸŽ‰ All contracts deployed successfully +``` + +:::info + +All your contract deployment addresses are stored in `flow.json`. Mainnet, Testnet and local (emulator) are stored as well. - -Flow Testnet is explicitly for experimentation and testing and should not be used to exchange "real value" (e.g. developing a fiat money on/off-ramp for your testnet application). - +::: + +## Deploy updated contracts on mainnet + +Contracts can be updated and retain the contract address. You can use the [Flow CLI contract update command] to redeploy an updated version of your contract: + +```zsh +flow accounts update-contract ./YourContract.cdc --signer mainnet-account --network mainnet +``` + +[Flow CLI]: ../../../build/tools/flow-cli/install +[Getting Started]: ../../../blockchain-development-tutorials/cadence/getting-started/smart-contract-interaction +[Smart Contract Testing Guidelines]: ./testing.md +[Create a Project]: ../../../build/tools/flow-cli/index.md +[Flow CLI contract update command]: ../../../build/tools/flow-cli/accounts/account-update-contract.md +[Flow CLI get account command]: ../../../build/tools/flow-cli/accounts/get-accounts.md +[Sporks]: ../../../protocol/node-ops/node-operation/network-upgrade +[Flow Emulator]: ../../../build/tools/emulator +[Testnet Faucet]: https://faucet.flow.com/ +[core contracts]: ../core-contracts/index.md +[some code examples from the Flow Go SDK]: https://github.com/onflow/flow-go-sdk/tree/master/examples +[Forum]: https://forum.flow.com/ +[Discord]: https://discord.com/invite/J6fFnh2xx6 diff --git a/docs/build/tools/emulator/index.md b/docs/build/tools/emulator/index.md index 451e772a64..d22893cc34 100644 --- a/docs/build/tools/emulator/index.md +++ b/docs/build/tools/emulator/index.md @@ -24,7 +24,17 @@ Then start the Flow Emulator: flow emulator ``` +You'll see output similar to: + +```bash +INFO[0000] βš™οΈ Using service account 0xf8d6e0586b0a20c7 serviceAddress=f8d6e0586b0a20c7 ... +INFO[0000] 🌱 Starting Flow Emulator +INFO[0000] πŸ›  GRPC server started on 127.0.0.1:3569 +INFO[0000] πŸ“‘ HTTP server started on 127.0.0.1:8080 +``` + This starts a local Flow network with: + - gRPC server on port `3569` - REST API on `http://localhost:8888` - Admin API on port `8080` @@ -40,6 +50,12 @@ flow emulator --block-time 1s # Persist state between restarts flow emulator --persist + +# Change the gRPC and REST API ports +flow emulator --port 9000 --rest-port 9001 + +# For a complete list of available flags, run: +flow emulator --help ``` For all available options, see the [CLI commands overview](../flow-cli/index.md). @@ -49,6 +65,36 @@ For all available options, see the [CLI commands overview](../flow-cli/index.md) - **Code Coverage**: Add `--coverage-reporting` flag and visit `http://localhost:8080/emulator/codeCoverage` - **Debugging**: Use `#debugger()` pragma in Cadence code for breakpoints +## Snapshots + +The Flow CLI provides a command to create emulator snapshots, which are points in blockchain history you can later jump to and reset the state to that moment. This can be useful for testing where you establish a beginning state, run tests and after revert back to the initial state. + +### Create a new snapshot + +Create a new emulator snapshot at the current block with a name of `myInitialState`. + +```shell +flow emulator snapshot create myInitialState +``` + +### Load an existing snapshot + +To jump to a previously created snapshot we use the load command in combination with the name. + +```shell +flow emulator snapshot load myInitialState +``` + +### List all existing snapshots + +To list all the existing snapshots we previously created and can load to run: + +```shell +flow emulator list +``` + +To learn more about using the Emulator, have a look at the [README of the repository](https://github.com/onflow/flow-emulator). + ## Additional Resources For advanced configuration options, see the [Flow Emulator repository](https://github.com/onflow/flow-emulator/). diff --git a/docs/build/tools/flow-cli/deployment/emulator-snapshot.md b/docs/build/tools/flow-cli/deployment/emulator-snapshot.md deleted file mode 100644 index a1782c0f72..0000000000 --- a/docs/build/tools/flow-cli/deployment/emulator-snapshot.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Create Emulator Snapshot -description: How to start create emulator snapshot from the command line -sidebar_position: 4 ---- - -The Flow CLI provides a command to create emulator snapshots, which are points in blockchain -history you can later jump to and reset the state to that moment. This can be useful for testing where you -establish a begining state, run tests and after revert back to the initial state. - -The command syntax is: -```shell -flow emulator snapshot create|load|list {name} -``` - -## Example Usage - -### Create a new snapshot -Create a new emulator snapshot at the current block with a name of `myInitialState`. -```shell -> flow emulator snapshot create myInitialState -``` - -### Load an existing snapshot -To jump to a previously created snapshot we use the load command in combination with the name. -```shell -> flow emulator snapshot load myInitialState -``` - -### List all existing snapshots -To list all the existing snapshots we previously created and can load to we run the following command: -```shell -> flow emulator list -``` - - -To learn more about using the Emulator, have a look at the [README of the repository](https://github.com/onflow/flow-emulator). - -## Flags - -### Emulator Flags -You can specify any [emulator flags found here](https://github.com/onflow/flow-emulator#configuration) and they will be applied to the emulator service. - -### Configuration - -- Flag: `--config-path` -- Short Flag: `-f` -- Valid inputs: valid filename - -Specify a filename for the configuration files, you can provide multiple configuration -files by using `-f` flag multiple times. - -### Version Check - -- Flag: `--skip-version-check` -- Default: `false` - -Skip version check during start up to speed up process for slow connections. diff --git a/docs/build/tools/flow-cli/deployment/start-emulator.md b/docs/build/tools/flow-cli/deployment/start-emulator.md deleted file mode 100644 index e5e55ff15b..0000000000 --- a/docs/build/tools/flow-cli/deployment/start-emulator.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Start Emulator -description: How to start the Flow Emulator from the command line -sidebar_position: 1 ---- - -The Flow Emulator is a lightweight development tool that mimics the behavior of the real Flow network. It is bundled with the [Flow CLI](https://docs.onflow.org/flow-cli/), which makes starting and configuring the emulator straightforward. - -## Initial Configuration - -The emulator requires a configuration file (`flow.json`). If you don’t already have one, create it using the `flow init` command: - -```bash -flow init -``` - -This initializes a default configuration file that the emulator will use. - -## Starting the Emulator - -To start the emulator with default settings, use the following command: - -```bash -flow emulator -``` - -This will start the emulator with the configuration defined in `flow.json`. - -### Example Output - -When you run the `flow emulator` command, you will see output similar to the following: - -```bash -INFO[0000] βš™οΈ Using service account 0xf8d6e0586b0a20c7 serviceAddress=f8d6e0586b0a20c7 ... -INFO[0000] 🌱 Starting Flow Emulator -INFO[0000] πŸ›  GRPC server started on 127.0.0.1:3569 -INFO[0000] πŸ“‘ HTTP server started on 127.0.0.1:8080 -``` - -## Customizing the Emulator - -You can customize the emulator behavior by using flags. Here are some examples: - -Change the gRPC and REST API ports: - -```bash -flow emulator --port 9000 --rest-port 9001 -``` - -Enable persistence of state across restarts: - -```bash -flow emulator --persist -``` - -Enable detailed logs for debugging: - -```bash -flow emulator --verbose -``` - -For a complete list of available flags, run: - -```bash -flow emulator --help -``` - -## Learn More - -To explore advanced features like snapshots, rollbacks, and debugging, visit the [Flow Emulator README](https://github.com/onflow/flow-emulator). \ No newline at end of file diff --git a/vercel.json b/vercel.json index 3e8e94a285..72115ffebd 100644 --- a/vercel.json +++ b/vercel.json @@ -2044,16 +2044,29 @@ "permanent": true }, { - "source": "/ecosystem/Hackathons and Events/may-the-flow-be-with-you", + "source": "/ecosystem/Hackathons%20and%20Events/may-the-flow-be-with-you", "destination": "/ecosystem/hackathons-and-events", "permanent": true }, { - "source": "/ecosystem/Hackathons and Events", + "source": "/ecosystem/Hackathons%20and%20Events", "destination": "/ecosystem/hackathons-and-events", + "permanent": true + }, + { "source": "/protocol/staking/staking-guide", "destination": "/protocol/staking", "permanent": true + }, + { + "source": "/build/tools/flow-cli/deployment/emulator-snapshot", + "destination": "/build/tools/emulator", + "permanent": true + }, + { + "source": "/build/tools/flow-cli/deployment/start-emulator", + "destination": "/build/tools/emulator", + "permanent": true } ] }