From e10619d27c9c9378cda3b769135567296a85501c Mon Sep 17 00:00:00 2001 From: Frank Chen Date: Wed, 14 Feb 2024 11:46:47 -0800 Subject: [PATCH 1/3] add playground tutorial to deploy and execute --- documentation/leo/07_leo_playground.md | 156 ++++++++++++++++++ .../leo/{07_resources.md => 08_resources.md} | 0 .../leo/{08_auction.md => 10_auction.md} | 2 +- .../{10_basic_bank.md => 11_basic_bank.md} | 5 + documentation/leo/12_vote.md | 2 +- documentation/leo/13_token.md | 2 +- .../leo/{11_tictactoe.md => 14_tictactoe.md} | 2 +- .../{14_battleship.md => 15_battleship.md} | 2 +- 8 files changed, 166 insertions(+), 5 deletions(-) create mode 100644 documentation/leo/07_leo_playground.md rename documentation/leo/{07_resources.md => 08_resources.md} (100%) rename documentation/leo/{08_auction.md => 10_auction.md} (99%) rename documentation/leo/{10_basic_bank.md => 11_basic_bank.md} (98%) rename documentation/leo/{11_tictactoe.md => 14_tictactoe.md} (98%) rename documentation/leo/{14_battleship.md => 15_battleship.md} (99%) diff --git a/documentation/leo/07_leo_playground.md b/documentation/leo/07_leo_playground.md new file mode 100644 index 000000000..49e10f1c5 --- /dev/null +++ b/documentation/leo/07_leo_playground.md @@ -0,0 +1,156 @@ +--- +id: playground +title: Leo Playground +sidebar_label: Leo Playground +--- + +Using [Leo Playground](https://play.leo-lang.org/) is pretty self-explanatory. You can shift through the provided examples, both basic and advanced, to better understand the functionalities of Leo and Aleo instructions. + +Some developers choose to write entire programs in Leo playground - it's an ideal place to check that your programs compile and run, without your needing to download [Leo](https://developer.aleo.org/leo/installation) itself (although we highly recommend it, and if you want to execute locally on your machine, you'll need it). + +You may choose to download any of the examples or programs you've written on your own in Playground and deploy them on a devnet. A tutorial to do that is provided below when you reach that step! + +## 1. Tools for Deployment + +- Install [Leo](https://developer.aleo.org/leo/installation) +- Install [Aleo's transaction cannon](https://github.com/AleoHQ/tx-cannon), which will help you deploy, execute, and stress test your Leo programs. +- Install [snarkOS](https://github.com/AleoHQ/snarkOS), which will help spin up a live devnet either locally or on AWS. +- Install [tmux](https://formulae.brew.sh/formula/tmux), because the devnet dashboard uses it. + +## 2. Start a local Aleo Devnet + +```bash +cd snarkOS +./devnet.sh + +Enter the total number of validators (default: 4): 4 +Do you want to run 'cargo install --path .' to build the binary? (y/n, default: y): n +Do you want to clear the existing ledger logs? (y/n, default: n): n +``` + +Right when the node starts, you'll see information for node 0, copy this down! + +```bash +- πŸ‘‹ Welcome to Aleo! We thank you for running a node and supporting privacy. +- πŸ”‘ Your development private key for node 0 is +- πŸͺͺ Your Aleo address is
+- 🧭 Starting a validator node on Aleo Testnet 3 Phase 3 at 0.0.0.0:4130 +- 🌐 Starting the REST server at 0.0.0.0:3030 +- πŸ”‘ Your one-time JWT token is +``` + +If you missed it because it scrolled too fast, use these `tmux` commands to scroll up: + +```bash +ctrl+b+[ # enter scroll mode to scroll up +ctrl+b+w # see all 4 validator nodes +ctrl+b+:kill-session # kills the session +q # exit ctrl+b mode +``` + + +Check that your network is running by using http://localhost:3030/testnet3/latest/height in your browser. The height should increase as a sign that your network is alive. + + +## 3. Execute Your Playground Project Locally + +Navigate back to your Playground project and run one of your transition functions `leo run `. + +What basically happens is the `.leo` program (in the program folder) is compiled to `.aleo` and executed locally. + +## 4. Deploying your Program on Devnet + +Let’s deploy the your program on the local devnet you just spun up. + + +Remember you started a clean devnet running at http://localhost:3030. What we want to do now is to deploy your program to that network. + +Again, make sure it's running: http://localhost:3030/testnet3/latest/height + +The height number should be moving up. + + +### Transaction Cannon Deployment + +Use the transaction cannon to deploy your program. + +```bash +cd +tx-cannon deploy /build/.aleo -k --fee 3 -e http://localhost:3030 +``` + +You can check that your deployment was successful on your network using: http://localhost:3030/testnet3/transaction/``. + +## 6. Execution On-Chain using the Transaction Cannon + +Once your program has been deployed on devnet, it's easy to execute your program on-chain. Create a `.toml` file with these parameters. You can find various examples in the repository with different inputs. The example shown below is for `helloworld.aleo`. + +```toml +# helloworld.aleo +[[step]] +private_keys = ["your-node-private-key"] +order = 0 +program_id = "helloworld.aleo" +function = "main" +inputs = [ "5u32", "5u32" ] +fee = 3 +``` + +The `.toml` file basically orders transactions to be executed. When we call the `tx-cannon execute` command, we ask it to look for the program we deployed on our local devnet and execute it using the provided inputs and the corresponding private key. + +```bash +tx-cannon batch-execute --test helloworld.toml -e http://localhost:3030 +``` + +Again, check that the program executed: http://localhost:3030/testnet3/transaction/``. + +There's much more functionality to be explored in the [tx-cannon repository](https://github.com/AleoHQ/tx-cannon). You can batch deploy, execute, and transfer, so take advantage of this tool to run development tests on your application! + +Congratulations, you took a project off Playground and successfully deployed it to an Aleo devnet! + +## 7. Claim your Leo Contributor Badge! + +Making it through this tutorial was no easy task, so because you've done it, we'd love to honor you with a Leo contributor badge on Github! + +### Pushing your Leo Application to Github + +1. Let's get to your project's directory, initialize, and commit your application. + +```bash +cd aleo-project +git init -b main +git add . +git commit -m "first commit, new aleo app" +``` + +2. Create a new repository on your [github.com](https://github.com/new) account by hitting "new repository" in the top right. Set the repo to public, and don't worry about adding a README, license, or .gitignore files. You can add these files after your project has been pushed to GitHub. + +3. At the top of the page your new repository, click to copy the remote repository URL and go back to your terminal to link your local project to this repository. + +![ ](https://docs.github.com/assets/cb-48149/mw-1440/images/help/repository/copy-remote-repository-url-quick-setup.webp) + +```bash +git remote add origin +git remote -v +git push -u origin main +``` + +### Claim your Leo badge +1. Go to the Leo repo issues tab [here](https://github.com/AleoHQ/leo/issues/new/choose) +2. Go to πŸ₯‡ "Badge" and click "Get Started". +3. Follow the brief instructions and submit. +4. Once your issue is approved, we will add you to the [contributors section](https://github.com/AleoHQ/leo#%EF%B8%8F-contributors) of the Leo README.md file. + +Congratulations on becoming a Leo contributor! πŸŽ‰ + +## 8. Recap & Additional Resources + +1. You downloaded a project off of [Leo Playground](https://play.leo-lang.org/). + +2. You installed [Leo](https://developer.aleo.org/leo/), our statically-typed programming language built for writing private applications, our [transaction cannon](https://github.com/AleoHQ/tx-cannon) for easy deployment and execution, and [snarkOS](https://github.com/AleoHQ/snarkOS), the data availability layer. + +3. You started a local devnet using the snarkOS repository. + +4. Using Leo, you compiled and locally executed your Leo program. + +5. Using the transaction cannon, you deployed and executed your program on-chain to a local devnet. \ No newline at end of file diff --git a/documentation/leo/07_resources.md b/documentation/leo/08_resources.md similarity index 100% rename from documentation/leo/07_resources.md rename to documentation/leo/08_resources.md diff --git a/documentation/leo/08_auction.md b/documentation/leo/10_auction.md similarity index 99% rename from documentation/leo/08_auction.md rename to documentation/leo/10_auction.md index 11a5b9f74..9c4ff292f 100644 --- a/documentation/leo/08_auction.md +++ b/documentation/leo/10_auction.md @@ -1,6 +1,6 @@ --- id: auction -title: A Private Auction on Aleo +title: A Private Auction using Leo --- ## Summary diff --git a/documentation/leo/10_basic_bank.md b/documentation/leo/11_basic_bank.md similarity index 98% rename from documentation/leo/10_basic_bank.md rename to documentation/leo/11_basic_bank.md index ff50811d5..bc5c091c3 100644 --- a/documentation/leo/10_basic_bank.md +++ b/documentation/leo/11_basic_bank.md @@ -1,3 +1,8 @@ +--- +id: basic bank +title: A Basic Bank using Leo +--- + ## Summary This program implements a bank that issues tokens to users and allows users to deposit tokens to accrue simple interest on their deposits. diff --git a/documentation/leo/12_vote.md b/documentation/leo/12_vote.md index d060247bc..72ce42c11 100644 --- a/documentation/leo/12_vote.md +++ b/documentation/leo/12_vote.md @@ -1,6 +1,6 @@ --- id: vote -title: A general vote program. +title: A Voting Program using Leo --- ## Summary diff --git a/documentation/leo/13_token.md b/documentation/leo/13_token.md index 030fa297f..e9a824326 100644 --- a/documentation/leo/13_token.md +++ b/documentation/leo/13_token.md @@ -1,6 +1,6 @@ --- id: token -title: A transparent & shielded custom token in Leo. +title: A Custom Token in Leo --- ## Summary diff --git a/documentation/leo/11_tictactoe.md b/documentation/leo/14_tictactoe.md similarity index 98% rename from documentation/leo/11_tictactoe.md rename to documentation/leo/14_tictactoe.md index e488d6596..da65e0bb8 100644 --- a/documentation/leo/11_tictactoe.md +++ b/documentation/leo/14_tictactoe.md @@ -1,6 +1,6 @@ --- id: tictactoe -title: A standard game of Tic-Tac-Toe in Leo. +title: A Game of Tic-Tac-Toe in Leo --- ## Summary diff --git a/documentation/leo/14_battleship.md b/documentation/leo/15_battleship.md similarity index 99% rename from documentation/leo/14_battleship.md rename to documentation/leo/15_battleship.md index 88de01b6b..f2795ac6e 100644 --- a/documentation/leo/14_battleship.md +++ b/documentation/leo/15_battleship.md @@ -1,6 +1,6 @@ --- id: battleship -title: A battleship game in Leo +title: A Game of Battleship in Leo --- ## Contents From b8e9b3437ba482f0990921a957bc31b52984f955 Mon Sep 17 00:00:00 2001 From: Frank Chen Date: Wed, 14 Feb 2024 14:40:21 -0800 Subject: [PATCH 2/3] fixed broken links --- documentation/leo/07_leo_playground.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/documentation/leo/07_leo_playground.md b/documentation/leo/07_leo_playground.md index 49e10f1c5..b2403672e 100644 --- a/documentation/leo/07_leo_playground.md +++ b/documentation/leo/07_leo_playground.md @@ -12,10 +12,12 @@ You may choose to download any of the examples or programs you've written on you ## 1. Tools for Deployment + - Install [Leo](https://developer.aleo.org/leo/installation) - Install [Aleo's transaction cannon](https://github.com/AleoHQ/tx-cannon), which will help you deploy, execute, and stress test your Leo programs. - Install [snarkOS](https://github.com/AleoHQ/snarkOS), which will help spin up a live devnet either locally or on AWS. - Install [tmux](https://formulae.brew.sh/formula/tmux), because the devnet dashboard uses it. + ## 2. Start a local Aleo Devnet @@ -72,6 +74,7 @@ The height number should be moving up. ### Transaction Cannon Deployment + Use the transaction cannon to deploy your program. ```bash @@ -80,6 +83,7 @@ tx-cannon deploy /build/.aleo -k `. + ## 6. Execution On-Chain using the Transaction Cannon @@ -98,6 +102,7 @@ fee = 3 The `.toml` file basically orders transactions to be executed. When we call the `tx-cannon execute` command, we ask it to look for the program we deployed on our local devnet and execute it using the provided inputs and the corresponding private key. + ```bash tx-cannon batch-execute --test helloworld.toml -e http://localhost:3030 ``` @@ -105,6 +110,7 @@ tx-cannon batch-execute --test helloworld.toml -e http://localhost:3030 Again, check that the program executed: http://localhost:3030/testnet3/transaction/``. There's much more functionality to be explored in the [tx-cannon repository](https://github.com/AleoHQ/tx-cannon). You can batch deploy, execute, and transfer, so take advantage of this tool to run development tests on your application! + Congratulations, you took a project off Playground and successfully deployed it to an Aleo devnet! @@ -147,7 +153,9 @@ Congratulations on becoming a Leo contributor! πŸŽ‰ 1. You downloaded a project off of [Leo Playground](https://play.leo-lang.org/). + 2. You installed [Leo](https://developer.aleo.org/leo/), our statically-typed programming language built for writing private applications, our [transaction cannon](https://github.com/AleoHQ/tx-cannon) for easy deployment and execution, and [snarkOS](https://github.com/AleoHQ/snarkOS), the data availability layer. + 3. You started a local devnet using the snarkOS repository. From 5e1a47f5bc943e694ff8ab96c3d6f1a5a581d2ce Mon Sep 17 00:00:00 2001 From: Frank Chen Date: Wed, 14 Feb 2024 14:50:53 -0800 Subject: [PATCH 3/3] fix more broken links --- documentation/00_getting_started.md | 2 +- documentation/00_leo_overview.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/00_getting_started.md b/documentation/00_getting_started.md index 5b389ee82..d89f952c7 100644 --- a/documentation/00_getting_started.md +++ b/documentation/00_getting_started.md @@ -84,4 +84,4 @@ If you're interested in learning more about Aleo: ✍️ | Community Blog ~ **https://medium.com/@AleoHQ** -### Looking for [**Developer Resources?**](./leo/07_resources.md) +### Looking for [**Developer Resources?**](./leo/08_resources.md) diff --git a/documentation/00_leo_overview.md b/documentation/00_leo_overview.md index ba9f4ced2..3553d39d1 100644 --- a/documentation/00_leo_overview.md +++ b/documentation/00_leo_overview.md @@ -52,13 +52,13 @@ The Leo CLI provides a suite of commands to make programming in Leo easy. ## Additional Material Install Leo for your favorite code [**editor**](./leo/06_tooling.md). -For additional developer resources such as examples and community projects, see [**Developer Resources**](./leo/07_resources.md). +For additional developer resources such as examples and community projects, see [**Developer Resources**](./leo/08_resources.md). -Is your Leo code formatted correctly? Check out the [**Style Guide**](./leo/07_resources.md#style-guide) and [**Common Patterns**](./leo/07_resources.md#common-patterns) for the official guidelines. +Is your Leo code formatted correctly? Check out the [**Style Guide**](./leo/08_resources.md#style-guide) and [**Common Patterns**](./leo/08_resources.md#common-patterns) for the official guidelines. Found a bug? Have an idea for a feature? File an issue on the [**Leo GitHub**](https://github.com/AleoHQ/leo/issues/new/choose). -See the [**Contributing Guide**](./leo/07_resources.md#contributing) for more information. +See the [**Contributing Guide**](./leo/08_resources.md#contributing) for more information. ## Examples -- [Private Auction](./leo/08_auction.md) \ No newline at end of file +- [Private Auction](./leo/10_auction.md) \ No newline at end of file