diff --git a/.github/workflows/build-binaries.yaml b/.github/workflows/build-binaries.yaml index 230f2f70..5d559d06 100644 --- a/.github/workflows/build-binaries.yaml +++ b/.github/workflows/build-binaries.yaml @@ -15,8 +15,10 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: - # macos-14 is the Apple Silicon M1 runner - os: [ubuntu-20.04, windows-latest, macos-latest, macos-14] + # macos-14 is the Apple Silicon M1 runner (mac os 14) + # macos-13 is the last available Intel Mac runner (mac os 13) + # See https://github.com/actions/runner-images?tab=readme-ov-file#available-images + os: [ubuntu-20.04, windows-latest, macos-13, macos-14] steps: - name: Checkout source code diff --git a/docs/imgs/algokitcodetour.png b/docs/imgs/algokitcodetour.png new file mode 100644 index 00000000..67538908 Binary files /dev/null and b/docs/imgs/algokitcodetour.png differ diff --git a/docs/imgs/algokitdemo.png b/docs/imgs/algokitdemo.png deleted file mode 100644 index dd88d909..00000000 Binary files a/docs/imgs/algokitdemo.png and /dev/null differ diff --git a/docs/imgs/algokitplayground.png b/docs/imgs/algokitplayground.png index 494de2c5..d8106a45 100644 Binary files a/docs/imgs/algokitplayground.png and b/docs/imgs/algokitplayground.png differ diff --git a/docs/imgs/dappflow.png b/docs/imgs/dappflow.png deleted file mode 100644 index 2b8ee68d..00000000 Binary files a/docs/imgs/dappflow.png and /dev/null differ diff --git a/docs/imgs/dappflow1.png b/docs/imgs/dappflow1.png deleted file mode 100644 index 2f2ccb38..00000000 Binary files a/docs/imgs/dappflow1.png and /dev/null differ diff --git a/docs/imgs/dappflow2.png b/docs/imgs/dappflow2.png deleted file mode 100644 index 4efe6c9d..00000000 Binary files a/docs/imgs/dappflow2.png and /dev/null differ diff --git a/docs/imgs/dappflow3.png b/docs/imgs/dappflow3.png deleted file mode 100644 index 4385a104..00000000 Binary files a/docs/imgs/dappflow3.png and /dev/null differ diff --git a/docs/imgs/dappflow4.png b/docs/imgs/dappflow4.png deleted file mode 100644 index 96fb0102..00000000 Binary files a/docs/imgs/dappflow4.png and /dev/null differ diff --git a/docs/imgs/dappflow5.png b/docs/imgs/dappflow5.png deleted file mode 100644 index 64d409c6..00000000 Binary files a/docs/imgs/dappflow5.png and /dev/null differ diff --git a/docs/imgs/dappflow6.png b/docs/imgs/dappflow6.png deleted file mode 100644 index 0030e3b5..00000000 Binary files a/docs/imgs/dappflow6.png and /dev/null differ diff --git a/docs/imgs/dappflow_transaction.png b/docs/imgs/dappflow_transaction.png deleted file mode 100644 index 3eda5de3..00000000 Binary files a/docs/imgs/dappflow_transaction.png and /dev/null differ diff --git a/docs/tutorials/intro.md b/docs/tutorials/intro.md index 9bb1f4e2..9c7960ec 100644 --- a/docs/tutorials/intro.md +++ b/docs/tutorials/intro.md @@ -2,7 +2,7 @@ AlgoKit is the primary tool used by the Algorand community to develop smart contracts on the Algorand blockchain. It provides the capabilities to develop, test and deploy Algorand smart contracts within minutes! This guide is intended to help you setup AlgoKit and to start developing your application. -## Quick start videos +## Quick start videos πŸ“Ή If you prefer videos, take a look at this 10 minute guide to getting started. @@ -10,19 +10,21 @@ If you prefer videos, take a look at this 10 minute guide to getting started. Detailed video guides for both [Windows](https://www.youtube.com/embed/22RvINnZsRo) and [Mac](https://www.youtube.com/embed/zsurtpCGmgE) are also available. -## Prequisites +> Please note, the videos above are to be refreshed to cover v2.0 features. For now, its best to follow the instructions below to get started. + +## Prequisites βœ… This guide presents installing AlgoKit using an OS agnostic procedure. For OS specific instructions take a look that the [AlgoKit install](https://github.com/algorandfoundation/algokit-cli/blob/main/README.md#install) guide. -Using this procedure requires the the following components be installed already +Before proceeding, ensure you have the following components installed: - [Python 3.10](https://www.python.org/downloads/) or higher -- [PipX](https://pypa.github.io/pipx/#on-linux-install-via-pip-requires-pip-190-or-later) -- [Git](https://github.com/git-guides/install-git#install-git) +- [pipx](https://pypa.github.io/pipx/#on-linux-install-via-pip-requires-pip-190-or-later) +- [git](https://github.com/git-guides/install-git#install-git) - [Docker](https://docs.docker.com/desktop/install/mac-install/) - [VSCode](https://code.visualstudio.com/download) -## Install AlgoKit +## Install AlgoKit πŸ›  To install AlgoKit, run the following command from a terminal. @@ -34,7 +36,9 @@ After the installation completes, **restart the terminal**. For more detailed installation documentation, see the [official installation guide](https://github.com/algorandfoundation/algokit-cli#install). -## Verify the Installation +> Please note, `pipx` is only one of the supported installation methods. You can also install AlgoKit via `brew` and _soon_ `winget` and `snap` as pre-build binaries. Refer to the official installation guide. + +## Verify the Installation βœ” To verify AlgoKit Installed correctly run the following. @@ -45,10 +49,10 @@ algokit --version Output similar to the following should be displayed: ```shell -algokit, version 0.5.0 +algokit, version 2.0.3 # or higher ``` -## Start a LocalNet +## Start a LocalNet 🌐 AlgoKit supports using a [local version of the Algorand blockchain](../features/localnet.md). To start an instance of this LocalNet run the following command from the terminal: @@ -60,7 +64,7 @@ This should start an instance of the LocalNet within docker. If you open the Doc ![Docker Desktop LocalNet Instance](../imgs/localnet.png) -## Create an AlgoKit project +## Create an AlgoKit project πŸ†• Now that AlgoKit is installed, you can rapidly create a new project to get started quickly. This can be done by running: @@ -70,102 +74,98 @@ algokit init This will launch a guided menu system to create a specific project tailored to your needs. The templates are basic starter applications for various Algorand development scenarios. To read more about templates checkout AlgoKit detailed documentation. -For now we'll use the `playground` template, which is a lightweight starting point for learning and experimentation. You can initialise a project using this template by running: +For now we'll use the `python` template, which is a lightweight starting point for learning Algorand smart contract development using Algorand Python. You can initialize a project using this template by running: ```shell -algokit init -t playground --no-workspace +algokit init -t python -a preset_name "starter" ``` Next, you will be prompted for the name of your project. Finally, select the default value for the rest of the prompts (enter). -Once finished, (if you have it installed) VS Code should automatically be opened with the initialised project and you will be prompted to install appropriate VS Code extensions. This starter app will contain one smart contract (built using the [Beaker](https://beaker.algo.xyz/) smart contract development framework) named `helloworld.py`, in the `hello_world` folder, with one method (`hello`) that takes a `String` and returns a `String`. +Once finished, (if you have it installed) VS Code should automatically be opened with the initialised project and you will be prompted to install appropriate VS Code extensions. This starter app will contain one smart contract (built using the [Algorand Python](https://algorandfoundation.github.io/puya/) language) named `contract.py`, in the `smart_contracts/hello_world` folder, with one method (`hello`) that takes a `String` and returns a `String`. Notice that within the contract folder, there is a `deploy_config.py` which defines the parameters for deployment of your smart contract to the target chain (Algorand TestNet, Algorand MainNet, Algorand LocalNet or else). ![AlgoKit Playground Contract](../imgs/algokitplayground.png) -## Run the Demo Application +## AlgoKit Project structure πŸ— + +The structure of your fresh algokit project instance will look similar to below: + +```bash +. +β”œβ”€β”€ .algokit.toml # Configuration for AlgoKit projects in the workspace. +β”œβ”€β”€ README.md # Quick start guide for the AlgoKit Workspace. +β”œβ”€β”€ {your_workspace|project_name}.code-workspace +└── projects + └── {your_project_name} # Root directory for the smart contract project. To add more projects into your algokit workspace run 'algokit init' from the root of your workspace repository. + β”œβ”€β”€ README.md # Quick start on Algorand Python smart contract template based project. + β”œβ”€β”€ .algokit # Hidden folder for AlgoKit AVM debugger and custom generators. + β”œβ”€β”€ .algokit.toml # Project-specific commands and custom generator references. + β”œβ”€β”€ poetry.lock + β”œβ”€β”€ poetry.toml # Dependency definitions for {your_project_name}. + β”œβ”€β”€ pyproject.toml # Project definitions for {your_project_name}. + └── smart_contracts + β”œβ”€β”€ README.md # Guide for adding new smart contracts. + β”œβ”€β”€ ... + β”œβ”€β”€ hello_world # Contract logic for 'hello_world'. + β”‚ β”œβ”€β”€ contract.py # Contract logic. + β”‚ └── deploy_config.py # Deployment logic for 'hello_world'. + └── helpers # Helper functions for contract build and deployment. +``` -Once the playground project is created, you will notice in the `hello_world` folder a file named `demo.py` which is a simple example of using AlgoKit to deploy and make a call to the `helloworld.py` smart contract on the LocalNet instance started earlier. +Additionally, each official smart contract template includes an interactive codespace walkthrough powered by [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour). -![AlgoKit Playground Demo](../imgs/algokitdemo.png) +To start the interactive walkthrough, install the extension and click on the green play button in the left bottom corner of the `Explorer` pane as demonstrated on the screenshot below (See `Getting Started with Your AlgoKit Project`). -Right clicking on this file and selecting `Run Python File in Terminal` will deploy the `HelloWorldApp` smart contract and then call it passing the parameter `name` with a value of `Beaker`. Alternatively, you can hit F5 (or whatever keyboard shortcut is set in VS Code for running the debugger) while you are viewing the `helloworld.py` file and it will: +![CodeTour Play Button](../imgs/algokitcodetour.png) -1. Start LocalNet -2. Build the smart contract -3. Deploy and call the smart contract (`demo.py`) +Upon execution, the walkthrough will guide you through the key components of your fresh AlgoKit project, which is an important prerequisite to learn before running and deploying your first smart contract. Certainly, not because its hard to learn, but because it will save you a lot of time and effort having the correct foundations. -This should produce something similiar to the following in the VSCode terminal. +## Run the Demo Application πŸƒβ€β™‚οΈ -```shell -(playground-py3.11) User@Algo-User-MBP myalgokit project % "/Users/user/code/algokit/myalgokit pro -ject/.venv/bin/python" "/Users/user/code/algokit/myalgokit project/playground/hello_world/demo.py" -Deployed app in txid SBNIJYZUOXVPXDFJHAVDDCO5TQ4WZ7P37QOOQM6CSVSMIURETHNQ - App ID: 11 - Address: 377KDIVHB7K2LFFJIPUPQFWJGVD36MAP4EI6Y2HAGRAW6JPK4MDUBC3YVY +Once the `Algorand Python` based project is created, you can get started by building and deploying your first smart contract. There are a few possible ways to do so as demonstrated on the following video. -Hello, Beaker -``` +[![Watch the video](https://ipfs.algonode.xyz/ipfs/Qmc9mRaPoDyhUFmek4ETxVfKUKzUg9pf3Tss5xwkBGdQis)](https://ipfs.algonode.xyz/ipfs/Qma6gNqxsSFc9Jbh8kBTZyVLv5gqFj1xnrsjoeT6MAAwCw/) The App ID of the deployed contract and its Algorand address is displayed, followed by the message returned from the smart contract call (`Hello, Beaker`). -At this point you have deployed a simple contract to an Algorand network and called it successfully! +1. Start LocalNet +2. Build the smart contract. Notice how a folder named `artifacts` is created with the [AVM (Algorand Virtual Machine)](https://developer.algorand.org/docs/get-details/dapps/avm/) related artifacts for deploying your smart contract. +3. Deploy and call the `HelloWorld` smart contract (from `contract.py` file). -Additionally, you can find the native TEAL smart contract code and the appropriate smart contract manifest JSON files have been output to the `artifacts` folder. +After execution, the `App ID` of the deployed contract and its Algorand address are displayed, followed by the message returned from the smart contract call (`Hello, world`). -![AlgoKit Playground Demo](../imgs/algokitartifacts.png) +At this point you have deployed a simple contract to a LocalNet Algorand network (running in your Docker environment) and called it successfully! -Running the `build.py` python file will also generate these artifacts without deploying. These files can be used by tools like [Dappflow](https://dappflow.org/), [goal](https://developer.algorand.org/docs/clis/goal/goal/), etc. to deploy your smart contract to the various Algorand networks. +Additionally, you can find the native AVM related artifacts and the appropriate smart contract manifest JSON files have been output to the `artifacts` folder. Note that in this example, AVM bytecode is compiled using the `PuyaPy` compiler, which is what `Algorand Python` relies on to compile your Python smart contract code to TEAL ([Transaction Execution Approval Language](https://developer.algorand.org/docs/get-details/dapps/avm/teal/)). -## Using Dappflow +### Using AlgoKit CLI to build and deploy contracts πŸ› οΈ -Dappflow is a web-based user interface that let's you visualise accounts, transactions, assets and applications on an Algorand network and also provides ability to deploy and call smart contracts. This works for TestNet, MainNet and also LocalNet. Furthermore, you can also create and fund accounts on LocalNet. While AlgoKit surfaces both a programming interface and a command line interface for interacting with Algorand, it also allows you to quickly open Dappflow so you can see what's happening visually. +When using official AlgoKit templates via `algokit init`, you can manage your projects using the AlgoKit CLI at the convenience of your terminal. -Dappflow can be launched from AlgoKit by running the following command from the VS Code terminal. +For example, to achieve the same results as in the demo earlier, build and deploy the `HelloWorld` contract from the `contract.py` file by running the following command from the terminal: ```shell -algokit explore +algokit project run build ``` -By default it will open Dappflow to point to LocalNet (It will be displayed as `sandnet-v1` in the upper left hand corner.), but you can pass in parameters to point it to TestNet and MainNet too. - -This command will launch your default web browser and load the Dappflow web application. - -**Note:** If you are using Safari, then it won't work against LocalNet and you will need to open it in a different browser. - -![AlgoKit Dappflow](../imgs/dappflow1.png) - -### Create test account - -To issue commands against the LocalNet network you need an account with ALGOs in it. Dappflow lets you easily create one. +This command will recompile your python contracts from `contract.py` and produce the necessary artefacts for deploying your contract. -Select `Dev Wallets` from the left menu and click on the `Create wallet` button. This will create an account on the LocalNet and fund it with 100 Algos that can be used to test with. - -![AlgoKit Dappflow](../imgs/dappflow2.png) - -In the bottom left hand corner of the menu, select `Connect wallet` and you will be prompted with several wallet choices. Choose the `Dev Wallet` option. This will connect the account you just created to Dappflow so you can use that account for signing transactions from the Dappflow user interface. - -### Deploy the Hello World application - -To deploy the built Beaker smart contract application, select the `Beaker studio` menu and click on the import beaker app. Select `File` and `Upload file`, browse to the artifacts created in the previous section of this guide. Select the `application.json` manifest file. This will load the specific manifest file for the Hello World sample application. - -![AlgoKit Dappflow](../imgs/dappflow3.png) - -To deploy this application again, select the `Create app` button followed by the `Create` button from the popup. You should get a `Transaction successful` message with the option to view the specific transaction in the explorer. Close out of the popup and then scroll down to the `ABI` section of the page. The `hello` method should be displayed with an execute button beside it. - -![AlgoKit Dappflow](../imgs/dappflow4.png) - -Click on the Execute button and a popup will be displayed allowing you to enter the parameter that we defined in the `HelloWorldApp` smart contract. - -![AlgoKit Dappflow](../imgs/dappflow5.png) +```shell +algokit project deploy localnet +``` -Enter a string in the parameter and click on `Execute`. You should get get a confirmation that the method executed properly and what the smart contract returned. +This will then deploy to your LocalNet instance and display the same output as in the earlier demo. -![AlgoKit Dappflow](../imgs/dappflow6.png) +> Please note, as highlighted in the [structure](#algokit-project-structure) section above, the `project run ...` commands are defined in the respective `.algokit.toml` file under `[project]` sections. -You have now successfully deployed and executed a smart contract method call using Dappflow! +## Next steps πŸšΆβ€β™‚οΈ -## Next steps +We have only covered a tiny fraction of the capabilities of the AlgoKit CLI and its related ecosystem of templates and utilities for an efficient developer experience. -- To learn more about AlgoKit and what you can do with it, checkout the [AlgoKit documentation](../algokit.md). -- To learn more about Beaker, take a look at the [Beaker documentation](https://beaker.algo.xyz/). +- To get the most out of `AlgoKit`, we recommend to get started with learning more about AlgoKit and what you can do with it by checking out our extensive [AlgoKit CLI documentation](../algokit.md). +- Explore the `README.md` files at the root of any project created via `algokit init`. All official AlgoKit templates include detailed quick started guides, an interactive code tour and various presets which can be customized to your needs. +- To learn more about `Algorand Python`, take a look at the [documentation](https://algorandfoundation.github.io/puya/). +- To learn more about the commands demonstrated in this tutorial, refer to [`init`](../features/init.md) and [`project`](../features/project.md) to get a comprehensive understanding of their further capabilities. +- If you'd like to learn more on structuring your `AlgoKit Project` as a monorepo, refer to `workspace` mode as described in [`init`](../features/init.md#workspaces-vs-standalone-projects). You can also pass the `--no-workspace` flag to setup a standalone algokit project, if preferred. +- If you'd like to **create your own** `AlgoKit` template, refer to the [template tutorial](./algokit-template.md). - More information on Algorand smart contracts is also available in the [smart contract documentation](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/). diff --git a/poetry.lock b/poetry.lock index ddcdc0bf..ab684cb6 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1200,13 +1200,13 @@ trio = ["async_generator", "trio"] [[package]] name = "jinja2" -version = "3.1.3" +version = "3.1.4" description = "A very fast and expressive template engine." optional = false python-versions = ">=3.7" files = [ - {file = "Jinja2-3.1.3-py3-none-any.whl", hash = "sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa"}, - {file = "Jinja2-3.1.3.tar.gz", hash = "sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90"}, + {file = "jinja2-3.1.4-py3-none-any.whl", hash = "sha256:bc5dd2abb727a5319567b7a813e6a2e7318c39f4f487cfe6c89c6f9c7d25197d"}, + {file = "jinja2-3.1.4.tar.gz", hash = "sha256:4a3aee7acbbe7303aede8e9648d13b8bf88a429282aa6122a993f0ac800cb369"}, ] [package.dependencies] @@ -3082,13 +3082,13 @@ files = [ [[package]] name = "tqdm" -version = "4.66.1" +version = "4.66.4" description = "Fast, Extensible Progress Meter" optional = false python-versions = ">=3.7" files = [ - {file = "tqdm-4.66.1-py3-none-any.whl", hash = "sha256:d302b3c5b53d47bce91fea46679d9c3c6508cf6332229aa1e7d8653723793386"}, - {file = "tqdm-4.66.1.tar.gz", hash = "sha256:d88e651f9db8d8551a62556d3cff9e3034274ca5d66e93197cf2490e2dcb69c7"}, + {file = "tqdm-4.66.4-py3-none-any.whl", hash = "sha256:b75ca56b413b030bc3f00af51fd2c1a1a5eac6a0c1cca83cbb37a5c52abce644"}, + {file = "tqdm-4.66.4.tar.gz", hash = "sha256:e4d936c9de8727928f3be6079590e97d9abfe8d39a590be678eb5919ffc186bb"}, ] [package.dependencies]