README.md

Caution

This is an experimental repo that is intended for power users developing core aspects of the ao computer, new ao unit implementations, or custom ao modules.

As such, this repo may become out-of-date and may not work out-of-the-box, and no Tier 1 support from the AO dev team is offered for this repository.

If you want to run aos processes, please refer to its source code or the ao cookbook.

ao-localnet

Run a complete AO Computer testbed, locally, with Docker Compose.

Purpose

The repo may helpful if you are doing one or more of the following:

1. Contributing to @permaweb/ao.
2. Compiling ao modules using the ao dev-cli.
   • And you want to avoid publishing each revision onto Arweave mainnet.
3. You are developing an ao component (e.g. a cu, mu, or su).
   • And you want to plug that into a working environment.
4. You are developing Lua code that will be loaded into aos processes.
   • And you want to avoid bricking your aos processes on ao testnet.

Quick Start Guide

1. Clone this repo.
2. Setup the necessary Arweave wallets:
   1. cd into the wallets directory (at the root of this repo).
   2. Run generateAll.sh to create new wallets for everything.
      • See wallets/README.md for more details.
   3. Run printWalletAddresses.mjs to list the addresses. (Useful for step 4, below.)
3. Boot up the localnet:
   1. Run docker compose up --detach.
      • You will need to have the Docker daemon running.
      • This could take a while the first time you run it.
   • You will have many services now bound to ports in the 4000 range (all subject to change):
     • http://localhost:4000/ - ArLocal (Arweave gateway/mock)
     • http://localhost:4007/ - A simple Arweave bundler/uploader
     • http://localhost:4004/ - An ao compute unit (cu).
     • http://localhost:4002/ - An ao messenger unit (cm).
     • http://localhost:4003/ - An ao schedule unit (su).
4. Seed data onto the blockchain:
   1. cd into the seed directory (at the root of this repo).
   2. Run ./download-aos-module.sh to pull a WASM binary from testnet.
   3. Set your wallet addresses (from step 2, above) in ./seed-for-aos.sh, then run it.
5. Run aos:
   1. cd into the aos directory (at the root of this repo).
   2. Run ./aos.

Additional Services

Note

You can optionally enable the following services. Powered by Docker Compose profiles

• ScAR (Arweave block explorer):
  • Run docker compose --profile explorer up.
  • http://localhost:4006/
• ArDrive Web:
  • Run docker compose --profile ardrive up.
  • http://localhost:4001/
  • Not fully functional. See below for more details.
• Turbo Upload Service (an Arweave uploader/bundlr):
  • Run docker compose --profile turbo up.
  • http://localhost:4005/
  • Not fully functional. See below for more details.

Development Status of this Repo

Warning

ao and aos are have just started working, but configuration (such as port mappings) will change soon and more usability features are planned.

• ✅ ArLocal instance mocking Arweave and acting as Arweave gateway.
  • ℹ️ There are some features missing from the upstream that tend to be used by block explorers, so we are using this fork, which fixes:
    • ✅ Added GET /tx/pending to fetch pending transaction ids
    • ✅ Added GET /raw/:txid to download raw transaction data
    • ✅ Fix some bugs in chunk uploading/downloading
    • ⬜ Blocks don't include block_size (#1)
    • ⬜ Blocks don't include reward_addr (#3)
    • ⬜ Blocks don't include weave_size (#2)
• ✅ Arweave block explorer (web interface).
  • ✅ ScAR - A lightweight option from here, forked here, with improvements.
  • ⬜ ArweaveWebWallet - Another option from here which powers https://arweave.app/.
• ✅ Fully functional ao computer, using the reference implementations.
  • ✅ cu
  • ✅ mu
  • ✅ su
• ✅ Successfully launching aos processes on the ao localnet.
• ⬜ Live reloading for cu and mu development.
  • A cool feature of Docker Compose.
• ⬜ nginx reverse proxy, for hostname routing
  • Currently in testing. This looks promising.
• ⬜ DNS routing
  • ✅ Routing *.ao-localnet.xyz to 127.0.0.1 and ::1
  • ℹ️ All containers should be reachable via *.ao-localnet.xyz domain names.
• ⚠️ Fully functional ArDrive Web (web interface)
  • ⏳ Known issues:
    • ℹ️ Arweave gateway port bug:
      • ✅ Fixed in arweave-dart@v3.8.4.
      • 💻 Hacked together by grep | sed replacing the dependency in ardrive-web@v2.37.2
      • 🙏 Hopefully fixed in the next version of ArDrive Web.
    • ⚠️ ArDrive Web is using so-called "sandboxed urls" where it contacts the gateway on a subdomain that is the base32 encoded transaction id of the Arweave transaction.
      • This can be resolved by adding 127.0.0.1 *.localhost to your /etc/hosts file.
      • Probably will be fixed with DNS routing, see above.
    • ⚠️ Cannot upload files due to missing Payment Service.
      • ArDrive Web doesn't respect its own configuration file setting: "useTurboPayment": false
      • Probably because this class member is hard coded?