permaweb / ao-cookbook

Get cooking with ao - the decentralized computer with infinite threads 🐰 🕳️ 👈

ao Cookbook

The ao Cookbook is meant to house small digestible code snippets for someone that has no experience with ao to be able to grab and go.

Contributing

The Cookbook is welcome to any and all contributions. Please refer to the project's style when contributing new snippets of code.

Structure

Currently we have "sections" under /src and the code for those sections.

Section	Description
Getting Started	Resources for starting development on ao
Core Concepts	Building blocks of ao that are good to know for development
Guides	Snack-sized guides about different tools for development
References	References to commonly needed code snippets

Writing References

References are an overarching topic with a list of references of how to do things under that topic. The general structure is the following:

Code Reference Title

Short Summary

Code Snippet

Writing Guides

Guides are longer form informational documentation on various topics. The general structure for writing a guide is the following:

Brief Summary/TLDR

Fact Sheet

Deep Dive

Other Resources

Building

If you use GitPod, this setup is done for you.

You need to have node v18 installed - https://nodejs.org

cd docs
yarn
yarn dev

Translation

Learn more about translating the cookbook here

Audit

If you find a tool or guide out of date, please create an issue on the project board so that it can be removed or updated.

Committing

We are using conventional commits for this repository.

To choose a task or make your own, do the following:

1. Add an issue for the task and assign it to yourself or comment on the issue
2. Make a draft PR referencing the issue.

The general flow for making a contribution:

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. Submit a Pull request so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

You can find tasks on the project board or create an issue and assign it to yourself.

Happy Cooking!

Deploy Instructions

Deploy is all handled by CI via a GitHub workflow

ao-cookbook's Issues

Styling // brand colors

Edited just colors to fit more arweave vibes. :)

opening inbox with aos> #Inbox doesnt work

process suggested in docs doesnt work

Fix: Fix the Token Blueprint code in the AO Cookbook

Description:
The code for tokens in the AO Cookbook is different from the code in the AO Stack. This is causing problems when sending tokens and other stuff.

Details:

• The code in the AO Cookbook doesn't match the code in the AO Stack.
• This is causing issues when trying to send tokens and doing other things with them.

To Do:

• We need to update the Token Blueprint code in the AO Cookbook to match the code in the AO Stack.
• After updating, we should test it to make sure everything works smoothly.

Related Links:

• AO Cookbook Token Blueprint
• AO Stack Token Blueprint

Guide: Inboxes and Handlers

Create a Guide on understanding Inboxes and Handlers

bug: when you refresh the browser on a cookbook getting started page you get not found

https://cookbook_ao.g8way.io/getting-started/

Maybe it should be

https://cookbook_ao.g8way.io/getting-started/index.html

or something

Set up CI to use ArDrive to publish the Cookbook

refactor aos guides to match aos changes

fix: try to get cookbook to deploy

Rename "Getting-Started" tutorial to "Begin"

To separate confusion from the "getting-started" guide, we need to rename the tutorial to "Begin." which was discussed in Slack.

Bug: Spelling Error in Index

Spelling error in the src/index for "walkthroughs".

ae79ecc

Bug: Update diagram for Processes

Tutorial: 0rbit Get Request Tutorial

ao brings the decentralized computation to a new level, and 0rbit is helping the devs bring ANY DATA to AO.

This issue is to add a tutorial in the ao cookbook's tutorial in a separate list with the name 0rbit - Get ANY DATA on AOS.

---

The tutorial will be maintained by me and @Lucifer0x17

Guide: Add Diagram for Messages

Cannot receive Morpheus's response.

According to this: https://cookbook_ao.g8way.io/tutorials/begin/messaging.html [Section: Message].
Cannot receive Morpheus's response after executing the send command.

Does mistake something? Or Morpheus isn't working fine?

Thanks.

bug: build failing

AOScan is now AOLink, and going into depht.

AOLink launched recently
I took the initiative to dive further into the features and provide updated screenshots.
And there should be no references to AOScan anymore.

enhancement(logo): need to update to new ao logo in the cookbook

Attached are light and dark

Need to make max-width 100px

use a more high resolution images

While reading the docs, I found the image's resolution not high enough.
Could we have a higher-resolution version here?

https://github.com/permaweb/ao-cookbook/blob/main/src/concepts/message-workflow-diagram.png

Implement Multilingual BUILD time translations

Support for multiple languages in static config is already supported. Ideally, we can use a process similar to the Permaweb Cookbook to use CI, in conjunction with GPT, to automatically generate the cookbook translated to other languages.

We have the raw materials and approach in the Permaweb Cookbook, just need time to port it over to the ao Cookbook.

PRs welcome!

bug - new references are not showing

update getting started guide

Guide: Editor Extensions

Rehydrate @martonlederer editor guide

An Error occurred trying to boot AOS. Please check your access points, if the problem persists contact support.

Guide: Working with Lua Tables and JSON

Create a guide on working with Lua Tables and JSON

toggle between themes not working as expected

The theme doesn't seem to toggle from dark to light mode as seen in the video below.

Screencast.from.08-03-24.10.57.32.PM.IST.webm

An Error occurred trying to boot AOS. Please check your access points, if the problem persists contact support.

An Error occurred trying to boot AOS. Please check your access points, if the problem persists contact support.

Recommended denomination for tokens

Hey there,
I'm a bit concerned about the recommended Denomination value in the cookbook. I feel like 10 is a very small number and it does not allow precise calculations (for e.g. exchange calculations). I understand the cookbook only has examples for this, but I feel like it should still be changed, because many developers will use it as a base. My recommendation is to have a Denomination of 10^12 in the tutorial, as well as the aos blueprint.
I also think it would make sense to recommend developers to only use integer powers of 10.

refactor: change tutorial into a bunch of little tutorials

bug: fix handler link

fix: try to get the cookbook to build on PR

feat(concept): How ao messages work

Add Concept on how ao messaging works

optimize the docs site heading and add language switcher

Hey, I'd like to optimize the heading of the docs site.

After we click on the Docs page, it shows a long list of menu and page links on the left.

I can optimize it to be the same style as the Vitepress official site.

I have read through the whole docs site, and I think I understand the whole docs now, and the new menu structure will be like this:

The screenshot is my Nuxt3 version of it, I understand that I need to build the structure in the Vitepress.

If permitted, I will start to work on this and make a PR for this including multiple language switchers with part of Chinese translation(We are working on progressing the whole docs into Chinese, about 50% for now).

AO from Stark@HelloRWA!

is it a `sh` or `lua`?

While I am reading the docs.

Have confusion about this:

the code type here is sh

  Send({ Target = "process ID", Data = "Hello World!" })

some times use:

the code type here is lua

Send({ Target = Morpheus, Data = "Morpheus?" })

What we should use then? I am working on translate the docs into Chinese, and at the same time I can optimize the docs in English too ;)

Guide: Using AOScan.xyz for Troubleshooting

Create a short guide introducing ao scan for troubleshooting

feat: refactoring cookbook from Sam

Accessing the msg.From field

Problem

The tutorials use msg.From as an authentication mechanism.

Solution

There is also msg.Tags.["From-Process"], or what is the difference?

Make an alt version of ao-cookbook

I just read through the ao cookbook.
It's exciting for the new tech!

I am just thinking about making a Chinese translation for the cookbook, at the same time, I make an alt version for the ao-cookbook, if you like, I can transfer the repo to permaweb org.

Source
Preview

Difference from ao-cookbook

• Move top-level item to the top nav
  • reduce the length of left aside menu
  • Only show sub-level menu items in the current top-level menu
• For multiple languages, making a different branch to host this with different sub-domains will be better.
• Support doc search internal
• Use Nuxt3 Docs Template
• Require to buy a Nuxt3 UI Pro license to deploy, it's ok to dev in localhost without the licence key

feat: add aOS Getting Started Guide

Using Messages in lua/aos guide

Create a guide which explains how to access different fields of a message when writing aos lua scripts

feat: add reference for data loading

Guide: Ownership of Processes

Ownership guide:

• Owner state
• Description on how you can complete it

Add Documentation Reference for ao library

ArDrive failing to upload `/assets/chunks/theme.b4WnDNzP.js`

Our CI uploads our Vitepress static site assets to ArDrive. Across CI runs, we're consistently seeing one file in those set of assets produce an error from ArDrive like:

Error uploading file file:///home/runner/work/.../.vitepress/dist/assets/chunks/theme.b4WnDNzP.js: Error: Upload to Turbo Has Failed. Status: 403 Text: Forbidden
Skipping and continuing...

We're using ArDrive CLI version 2.0.2 and uploading the entire directory using this command:

ardrive upload-file \
            --turbo \
            --parent-folder-id "${FOLDER_ID}" \
            --local-paths "${ARTIFACTS_OUTPUT_DIR}"/* \
            -w "..."

All of the other files, ~250 seem to upload to ArDrive just fine, it's just consistently that file. File is ~52KB.

Guide: FAQ

Create a guide for FAQs

• Ownership
• JSON
• when to use ao.send and Send

feat(aos): Expand Tutorial and build some guides with aos

feat: Reorg folders

After a discussion with Sam, we thought it was best to reorganize the folders as:

1. Tutorials
2. Guides
3. Concepts
4. References

--

Current:

1. Concepts
2. Guides
3. Tutorials
4. References

setup aos concepts and guides

aos

• installing aos
• checking the version
• command line arguments
• load command
• receiving/handling messages
• sending messages
• spawning processes

AO Connect Updates

Make sure ao connect guides are up to date

A Break In Navigation.

When going from the tutorial table of contents to the 1st step in the tutorial, it just takes you back to the "Getting Started" page. This creates a navigation loop. When completing the "Getting Started", it takes you to the Next Page which is "Concepts".

Loom Video to Demo:
https://www.loom.com/share/a0e8dea305064c34a9aec6bcde49c986

Suggested Changes:

• Create a new, condensed version of "Getting Started" to serve as the 1st page of the tutorial track. That way, when reaching the bottom the next page should be the suggested next step in the tutorial track.

Error trying to boot aos.

Description
Trying to boot aos but receiving An Error occurred trying to boot AOS. Please check your access points, if the problem persists contact support.

Desktop:

• macOS
• Version: 14.2.1
• BuildVersion: 23C71

Details

• Node v20.11.1

1. Ran npm i -g https://get_ao.g8way.io/
2. Ran aos
3. Received An Error occurred trying to boot AOS. Please check your access points, if the problem persists contact support.
4. Ran DEBUG=1. See screenshot below for output.
5. Ran HTTPS_PROXY=http://localhost:3000 aos → same output as step 3.

Screenshots