diff --git a/documentation/00_leo.md b/documentation/00_leo.md index 17f35b856..f2e388557 100644 --- a/documentation/00_leo.md +++ b/documentation/00_leo.md @@ -3,6 +3,7 @@ id: leo title: The Leo Programming Language sidebar_label: Leo --- +[general tags]: # (overview, leo) Leo is an open-source, statically-typed, imperative programming language designed for building private applications on the Aleo blockchain. It abstracts the complexities of zero-knowledge cryptography, enabling developers to create secure, privacy-preserving applications while abstracting technical complexities. diff --git a/documentation/01_new.md b/documentation/01_new.md index 023fe02a7..02615b5c9 100644 --- a/documentation/01_new.md +++ b/documentation/01_new.md @@ -3,11 +3,12 @@ id: new title: What's new on Leo? sidebar_label: What's new? --- +[general tags]: # (whats_new, leo) :::tip ### [**πŸ“¦ Releases**](https://github.com/ProvableHQ/leo/releases) - Stay up to date with the latest Leo releases. -// Use uparrao emoji -### [**πŸš€ Upgrade Guide**](./guides/03_program_upgradability.md) - Learn how to upgrade your Leo programs. -### [**βš›οΈ Create Leo App**](./sdk/create-leo-app/01_create_leo_app.md) - A full stack application written in Typescript using Leo and React. +### [**πŸš€ Upgrade Guide**](./guides/10_program_upgradability.md) - Learn how to upgrade your Leo programs. +### [**🀝 Core Developers Call**]( https://developer.aleo.org/guides/how_to_get_help) - Collaborate with the Leo development team and ecosystem on the future of Leo. +### [**βš›οΈ Create Leo App**](https://developer.aleo.org/category/create-leo-app) - A full stack application written in Typescript using Leo and React. ::: diff --git a/documentation/02_where.md b/documentation/02_where.md index adbfcd269..ee91fe762 100644 --- a/documentation/02_where.md +++ b/documentation/02_where.md @@ -3,6 +3,7 @@ id: where title: Where to go? sidebar_label: Where to go? --- +[general tags]: # (roadmap, leo) While a deep dive through the Leo documentation is a useful exercise, we realize that it may not be very practical. To help you along your journey, we've provided a "map" to help you find your way. @@ -12,7 +13,7 @@ While a deep dive through the Leo documentation is a useful exercise, we realize - If you're designing a dApp, we recommend checking out **Leo By Example** for a reference. -- If you're interested in advanced concepts, check out [**Guides**](./guides/00_overview.md) and [**Recipes**](./recipes/00_overview.md). Also be sure to check out the [**Core Aleo Concepts**](https://developer.aleo.org/references/faqs). +- If you're interested in tutorials, check out [**Guides**](./guides/00_overview.md). Also be sure to check out the [**Core Aleo Concepts**](https://developer.aleo.org/guides/faqs). - If you're deploying or running your programs, [**CLI**](./cli/00_overview.md) will be helpful. diff --git a/documentation/cli/00_overview.md b/documentation/cli/00_overview.md index c04a56cfa..54592d6a1 100644 --- a/documentation/cli/00_overview.md +++ b/documentation/cli/00_overview.md @@ -1,8 +1,9 @@ --- -id: overview +id: cli_overview title: The Leo Command Line Interface sidebar_label: Overview --- +[general tags]: # (cli) The Leo CLI is a command line interface tool that comes equipped with the Leo compiler. @@ -12,324 +13,52 @@ You can print the list of commands by running `leo --help` ## Commands -* [`account`](#leo-account) - Create a new Aleo account, sign and verify messages. -* [`new`](#leo-new) - Create a new Leo project in a new directory. -* [`build`](#leo-build) - Compile the current project. -* [`deploy`](#leo-deploy) - Generate proving and verifying keys and produce a transaction containing the deployment. -* [`run`](#leo-run) - Run a program without producing a proof. -* [`execute`](#leo-execute) - Execute a program and produce a transaction containing a proof. -* [`debug`](#leo-debug) - Run the interactive debugger in the current package. -* [`query`](#leo-query) - Retrieve metadata and state from the network. -* [`add`](#leo-add) - Add a new on-chain or local dependency to the current project. -* [`remove`](#leo-remove) - Remove a dependency from the current project. -* [`clean`](#leo-clean) - Clean the build and output artifacts. -* [`update`](#leo-update) - Update to the latest version of Leo. - ---- - - -## `leo account` - -[Back to Top](#commands) - -To create a new Aleo account, run: - -```bash -leo account new - - Private Key APrivateKey1zkp... - View Key AViewKey1... - Address aleo1... -``` - -:::warning -We urge you to exercise caution when managing your private keys. `leo account` cannot be used to recover lost keys. -::: - -To import an existing Aleo account, run: - -```bash -leo account import {$PRIVATE_KEY} -``` - -To create a new account and save it to your `.env` file, run: - -```bash -leo account new --write -```` - -`leo account` has a number of additional subcommands. To list all options, run: - -``` -leo account --help - -# Output: -Create a new Aleo account, sign and verify messages - -Usage: leo account [OPTIONS] - -Commands: - new Generates a new Aleo account - import Derive an Aleo account from a private key - sign Sign a message using your Aleo private key - verify Verify a message from an Aleo address - help Print this message or the help of the given subcommand(s) - -Options: - -d Print additional information for debugging - -q Suppress CLI output - --path Optional path to Leo program root folder - --home Optional path to Aleo program registry. - -h, --help Print help -``` - -To learn more about how to use `leo account` to sign and verify messages, check out [**Sign and Verify**](03_signing.md). - - -## `leo new` - -[Back to Top](#commands) - -To create a new project, run: -```bash -leo new {$NAME} -``` - -Valid project names are snake_case: lowercase letters and numbers separated by underscores. -This command will create a new directory with the given project name. - -See [Project Layout](../language/01_layout.md) for more details . - - -## `leo build` - -[Back to Top](#commands) - -To compile your program into Aleo Instructions and verify that it builds properly, run: -```bash -leo build -``` - -[//]: # (The results of compiling `main.leo` or `lib.leo` and it's imported dependencies will be printed:) - -[//]: # (```bash title="console output:") - -[//]: # ( Compiling Starting...) - -[//]: # ( Compiling Compiling main program... ("${NAME}/src/main.leo")) - -[//]: # ( Compiling Complete) - -[//]: # ( Done Finished in 10 milliseconds) - -[//]: # (```) -This will populate the directory `build/` (creating it if it doesn't exist) with an Aleo instructions file `.aleo`. -```bash title="console output:" - Leo βœ… Compiled 'main.leo' into Aleo instructions -``` - - -## `leo deploy` -[Back to Top](#commands) -:::tip -Use this command to deploy a program to the Aleo network. This requires having a funded account. -::: - -To deploy the project in the current working directory. -```bash -leo deploy // Defaults to using key information in `.env`, and deploys to `testnet3` via endoint `http://api.explorer.provable.com/v1`. -leo deploy --endpoint "{$ENDPOINT}" --private-key "{$PRIVATE_KEY}" // To deploy using custom private key, to a custom endpoint (e.g. local devnet `http://0.0.0.0:3030`). -``` - -See [Deploy](01_deploying.md) for more details. - -## `leo run` -[Back to Top](#commands) -:::tip -Use this command to run your program before [**executing**](#leo-execute) it. -::: - -To run a Leo transition function with inputs from the command line. -`{$INPUTS}` should be a list of inputs to the program separated by spaces. -```bash -leo run {$TRANSITION} {$INPUTS} -``` -This command does not synthesize the program circuit or generate proving and verifying keys. - -For the default program created by `leo new`, this command -```bash -leo run main 1u32 2u32 -``` -will generate this output - -```bash title="console output:" - Leo βœ… Compiled 'main.leo' into Aleo instructions - -β›“ Constraints - β€’ 'hello.aleo/main' - 33 constraints (called 1 time) - -➑️ Output - β€’ 3u32 - - Leo βœ… Finished 'hello.aleo/main' (in "/hello/build") -``` - -If one or more of your inputs are negatives, and consequently begin with a `-`, -you may separate the inputs with a `--` so that the command line parser -won't attempt to parse them as options: -```bash -leo run ${TRANSITION} -- {$INPUTS} -``` - -## `leo execute` -[Back to Top](#commands) -:::tip -Use this command to execute your program and generate a transaction object. -::: - -To execute a Leo transition function with inputs from the command line. -`{$INPUTS}` should be a list of inputs to the program separated by spaces. -```bash -leo execute {$TRANSITION} {$INPUTS} -``` -This command synthesizes the program circuit and generates proving and verifying keys. - - -```bash title="console output:" - Leo βœ… Compiled 'main.leo' into Aleo instructions - -β›“ Constraints - β€’ 'hello.aleo/main' - 33 constraints (called 1 time) - -➑️ Output - β€’ 3u32 - - {"type":"execute","id":"at1 ... (transaction object truncated for brevity) - - Leo βœ… Executed 'hello.aleo/main' (in "/hello/build") -``` - -:::info -The `-b` or `--broadcast` flag is required in order to broadcast a transaction to a network. -::: - -See [Execute](./02_executing.md) for more details. - - -## `leo debug` -[Back to Top](#commands) - -To start the interactive debugger, run `leo debug` in a Leo project. - -```bash -> leo debug - Leo βœ… Compiled sources for 'workshop' -This is the Leo Interpreter. Try the command `#help`. - -? Command? β€Ί -``` - -See [Debugging](./../testing/02_debugger.md) for more details. - - -## `leo query` -[Back to Top](#commands) - -Use `leo query` to get data from a network supporting the canonical `snarkOS` endpoints. - -```bash -Query live data from the Aleo network - -Usage: leo query [OPTIONS] - -Commands: - block Query block information - transaction Query transaction information - program Query program source code and live mapping values - stateroot Query the latest stateroot - committee Query the current committee - mempool Query transactions and transmissions from the memory pool - peers Query peer information - help Print this message or the help of the given subcommand(s) - -Options: - -d Print additional information for debugging - -e, --endpoint Endpoint to retrieve network state from. Defaults to entry in `.env`. - -n, --network Network to use. Defaults to entry in `.env`. - -q Suppress CLI output - --path Path to Leo program root folder - --home Path to Aleo program registry - -h, --help Print help -``` - - -## `leo add` -[Back to Top](#commands) -:::tip -Use this command to add a dependency to your program. This is a precursor to being able to import a program inside the leo source code file. -::: - -The command can be used to add an already deployed program as a project dependency. -`{$PROGRAM}` should be the name of the program to add as a dependency. -```bash -leo add {$PROGRAM} // {$NETWORK} defaults to `testnet`. -leo add -n {$NETWORK} {$PROGRAM} // To pull from a custom network. -``` - -The command can be used to add a local Leo program as a project dependency. -`{$PATH}` should be the relative path to the project directory. -```bash -leo add -l {$PATH} {$PROGRAM} -``` - -See [Dependency Management](./04_dependencies.md) for more details. - -## `leo remove` -[Back to Top](#commands) - -Removes the dependency, local or remote, from the project. - -```bash -leo remove credits.aleo -``` - -See [Dependency Management](./04_dependencies.md) for more details. - -## `leo clean` -[Back to Top](#commands) - -To clean the build directory, run: -```bash -leo clean -``` -```bash title="console output:" - Leo 🧹 Cleaned the outputs directory (in "...") - Leo 🧹 Cleaned the build directory (in "...") -``` - -## `leo update` -[Back to Top](#commands) - -To download and install the latest Leo version run: - -```bash -leo update -``` - -```bash title="console output:" -Checking target-arch... x86_64-apple-darwin - -Checking current version... v1.8.3 - -Checking latest released version... v1.8.3 - - Updating Leo is on the latest version 1.9.0 -``` - - -### `leo example` -[Back to Top](#commands) - -:::warning -`leo example` has been deprecated and will no longer be supported. -::: +* [`account`](./01_account.md) - Create a new Aleo account, sign and verify messages. + * [`new`](./01_account.md#leo-account-new) - Generates a new Aleo account. + * [`import`](./01_account.md#leo-account-import) - Derive and Aleo account from a private key. + * [`sign`](./01_account.md#leo-account-sign) - Sign a message using your Aleo private key. + * [`verify`](./01_account.md#leo-account-verify) - Verify a message and signature from an Aleo address. +* [`add`](./02_add.md) - Add a new onchain or local dependency to the current project. +* [`build`](./03_build.md) - Compile the current project. +* [`clean`](./04_clean.md) - Clean the build and output artifacts. +* [`debug`](./05_debug.md) - Run the interactive debugger in the current package. +* [`deploy`](./06_deploy.md) - Deploy a program to the Aleo network. +* [`devnet`](./07_devnet.md) - Initialize a local devnet. +* [`execute`](./08_execute.md) - Execute a program and produce a transaction containing a proof. +* [`new`](./09_new.md) - Create a new Leo project in a new directory. +* [`query`](./10_query.md) - Query live data and state from the Aleo network. + * [`block`](./10_query.md#leo-query-block) - Query block information. + * [`transaction`](./10_query.md#leo-query-transaction) - Query transaction information. + * [`program`](./10_query.md#leo-query-program) - Query program source code and live mapping values. + * [`stateroot`](./10_query.md#leo-query-stateroot) - Query the latest stateroot. + * [`committee`](./10_query.md#leo-query-committee) - Query the current committee. + * [`mempool`](./10_query.md#leo-query-mempool) - Query transactions and transmissions from the memory pool. + * [`peers`](./10_query.md#leo-query-peers) - Query peer information. +* [`remove`](./11_remove.md) - Remove a dependency from the current project. +* [`run`](./12_run.md) - Run a program without producing a proof. +* [`test`](./13_test.md) - Run the test cases for a Leo project. +* [`update`](./14_update.md) - Update to the latest version of Leo. +* [`upgrade`](./15_upgrade.md) - Upgrade a deployed program on the Aleo network. + +### Universal Flags: +These flags are available to use alongside all commands in the Leo CLI. + +#### `-h` +#### `--help` +Prints available commands and flags. + +#### `-V` +#### `--version` +Prints the currently installed version of Leo. + +#### `-q` +Suppresses the CLI output. + +#### `-d` +Prints out additional information for debugging if possible. + +#### `--path ` +Specifies the path to Leo program root folder. Defaults to `./`. + +#### `--home ` +Specifies the path to the `.aleo` program registry. This is where programs downloaded from the network will be cached. Defaults to `~/.aleo/registry`. diff --git a/documentation/cli/01_account.md b/documentation/cli/01_account.md new file mode 100644 index 000000000..6adc1691d --- /dev/null +++ b/documentation/cli/01_account.md @@ -0,0 +1,176 @@ +--- +id: cli_account +title: leo account +sidebar_label: Account +--- +[general tags]: # (cli, leo_account, account, sign, verify, signature, private_key, view_key, address) + +The `leo account` command is used to create and manage Aleo accounts, as well as sign and verify messages + +:::warning +We urge you to exercise caution when managing your private keys. `leo account` cannot be used to recover lost keys. +::: + + +## Subcommands +* [`new`](#leo-account-new) - Generates a new Aleo account. +* [`import`](#leo-account-import) - Derive and Aleo account from a private key. +* [`sign`](#leo-account-sign) - Sign a message using your Aleo private key. +* [`verify`](#leo-account-verify) - Verify a message and signature from an Aleo address. + +  + +--- + + +## `leo account new` + +[Back to Top](#subcommands) + +Use this command to generate a private key, view key, and address for a new Aleo account. + + +The output should look like this: +```bash title="console output:" + Private Key APrivateKey1zkp... + View Key AViewKey1... + Address aleo1... +``` + + +### Flags: +#### `--seed ` +#### `-s ` +Specifies a particular numeric value to use as the seed for the random number generator (RNG) + + + +#### `--write ` +#### `-w` +Writes the generated private key to a `.env` file in the current working directory (`./`) + + + +#### `--discreet` +Print sensitive information (such as private key) discreetly to an alternate screen + + +  + +--- + + + +## `leo account import` + +[Back to Top](#subcommands) + +Use this command to derive the view key and address for an Aleo account from a private key. + + +To import an existing Aleo account, run the following command: +```bash +leo account import +``` +where `` is your private key. + +### Flags: +#### `--write ` +#### `-w` +Writes the generated private key to a `.env` file in the current working directory (`./`) + + + +#### `--discreet` +Print sensitive information (such as private key) discreetly to an alternate screen + +  + +--- + +## `leo account sign` + +[Back to Top](#subcommands) + +Use this command to sign a message using your Aleo private key. + +Assuming either the current working directory is a Leo project or the `$PRIVATE_KEY` environment variable has been set, you can sign a message using the following command: +```bash +leo account sign --message +``` + +### Flags: +#### `--message ` +#### `-m ` + +:::info +This flag is required! +::: + +Specifies the message to be signed. + +--- + +#### `--private-key ` +Explicity specifies the private key to sign the message with. Overrides any private key in `.env` file or `$PRIVATE_KEY` environment variable. + + +#### `--private-key-file ` +Alternative way to explicity specifies the private key by reading from a text file at path `` Overrides any private key in `.env` file or `$PRIVATE_KEY` environment variable. + + +#### `--raw ` +#### `-r` +Parses the message as bytes instead of Aleo literals. + +  + +--- + +## `leo account verify` + +[Back to Top](#subcommands) + +Use this command to verify a message and signature from an Aleo address. + +To verify a message, run the following command +```bash +leo account verify --address
--signature --message +``` +where `` is the message, `` is the signature of that message, and `
` is the address of the account that generated the signature. + +### Flags: +#### `--address
` +#### `-a
` + +:::info +This flag is required! +::: + +Specifies the address of the account that generated the signature. + + +#### `--signature ` +#### `-s ` + +:::info +This flag is required! +::: + +Specifies the signature of the message. + + +#### `--message ` +#### `-m ` + +:::info +This flag is required! +::: + +Specifies the message that was signed. + + +#### `--raw ` +#### `-r` +Parses the message as bytes instead of Aleo literals. + diff --git a/documentation/cli/02_add.md b/documentation/cli/02_add.md new file mode 100644 index 000000000..6b8ae117c --- /dev/null +++ b/documentation/cli/02_add.md @@ -0,0 +1,59 @@ +--- +id: cli_add +title: leo add +sidebar_label: Add +--- +[general tags]: # (cli, leo_add, add_dependency, dependency, dependency_management, imports) + +The `leo add` command is used to add a new on-chain or local dependency to the current Leo project. + + +To add a local dependency to your project, run the following command: +```bash +leo add --local +``` +where `` is the name of the imported program, and `` is the path to the local project. + +  + +To add a program already deployed onchain as a dependency to your project, run the following command: +```bash +leo add --network +``` +where `` is the name of the imported program. + +### Flags: +#### `--local ` +#### `-l ` +Specifies that the dependency to be added is a local program located at path ``. This can either be the root directory for a Leo project, or a path directly to an already compiled `.aleo` file. + + +#### `--network` +#### `-n ` +Specifies that the dependency to be added is a remote program currently deployed onchain. The network that it will be pulled from will be the same as the one specified in by the `NETWORK` variable in `.env` + + + +#### `--edition ` +#### `-e ` +Specifies the expected edition of the program being imported. Only passing this flag will assume that the program is being imported from the network. + +:::warning +Do not use this feature unless you know what you are doing! +::: + + + +#### `--dev` +Specifies that the imported program is a development dependency and should not be used in production + + + +#### `-c` +#### `--clear` +Clears all previous dependencies. + +:::warning +This feature is currently bugged and is non-functional. +::: + diff --git a/documentation/cli/02_executing.md b/documentation/cli/02_executing.md deleted file mode 100644 index f682a213a..000000000 --- a/documentation/cli/02_executing.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: execute -title: Run Your Programs -sidebar_label: Execute ---- - - -The `leo execute` command is used to call functions from deployed programs. Under the hood, this commands downloads the program code from the specified network, synthesizes the program circuit, executes the function logic, generates proving verifying keys along with a zero-knowledge proof, and then submits a transaction object to the network. - -The full syntax for the `leo execute` command is: -```bash -leo execute [input_1] [input_2] ... [input_n] --program .aleo --broadcast -``` -As with the `leo deploy` command, you must specify the network, Private Key, and node endpoint parameters using either a `.env` file or environment variables. - -Developers have the option to inspect a transaction object before it is broadcast to the network using the `--dry-run` flag in lieu of the `--broadcast` flag. Invoking this flag will print the transaction output to `stdout`. - -```bash -leo execute [input_1] [input_2] ... [input_n] --program .aleo --dry-run -``` - -```bash -{"type":"execute","id":"at1lmse7pr4h0n3lv9mvn262up7v0nhyulm9ygn3kwpxym9008deygs4elkl9","execution":{"transitions":[{"id":"au1w7n6ahdjmvj2nz9nu6zhzq35v93nguwhv3tzqeywhntrxytmngpqfhg5ss","program":"example_program.aleo","function":"main","inputs":[{"type":"public","id":"692634202775738788892756541276479310312882753688899140142743446375832543859field","value":"2u32"},{"type":"private","id":"8385995819199163615771507865968584985436639267963028732797694416477829379079field","value":"ciphertext1qyqru0tr39h8kzquxjr7xfrud98m47mawmnvj5xlfnypzyvhepf7xzsawdtkl"}],"outputs":[{"type":"private","id":"3124422272714190443592630115423959519403736569564003413462129091659624867451field","value":"ciphertext1qyq08lr8g88k20xp6k9fr34l07fjaaddmdpnfpmdlxwz3mr6xrfjzqqf5nfna"}],"tpk":"4367604861311133041917107666803824204733856429271239279390409648472266500776group","tcm":"7471894725277672051255805412199677748935089735919789147124444004458893515904field","scm":"1788545946703859533314929059553927884362701746091184516349398904143684696559field"}],"global_state_root":"sr1pezvtfwkhq742lzngn8sc89t5s0ez4u64ux73dw2c7kvk5tjnqxqcz79km","proof":"proof1qyqsqqqqqqqqqqqpqqqqqqqqqqqfzm7qyhzn32nrg30d85qg7725jy8rnrhx5sp2xgkkx3jjzp3rttmg2lra09573rttj5pp0wmpx0cpq8xvl6s6zl3p6fn9hdqsyg5x2rz234l5g9knp0x6faex4dqxcpfs28rgy9rcl9qj8963g333f4egfqvqay0anlee9jwl9276cnh0kuhem3cafhacdyvpa74y28kkeuudxgufxg5qfd5h2sy520kjl8u8qsqh8e9rxlwp6v9059z8zzz26ytdcd7zdsl4l4xp2vn6aaanr0695knljv369h0xvphmxns7m5k7tpuqhptx8z6nvemvt7muchne4rx2rfmpv0pedxf8ms33pxte0hnlpfpdvtjnckcpejzwqjez8y70cyasppxggphh6fqehee9u58lklg3a750gxtjxxfq0z0g2cx0zmkf30tkwwqhlke7vljyswks4lynp46lqqudm45k79s27wgjluza8sc8vq8ld9evrqmj7mz4s9wm9qts4qzajl2f3q6t2f5mv55ctfp0svj3sqq8l6ujt79v93smpkcry9uxd87tdkypz8n2v0p35zrtkjjwh697gu6lxj5fpmu2x94m5gth8hnfy6qsvr9mn5adppml6wyzur60cuegjdnduhytqptpd2630aq5chht4h93flg0yzfq3har5dtnqcgxc0up09p9nt045c5umvlzuxkgzupsfdkarg0rzqdyy6n93fyeh25zru9nh96n04hm0aajjt0tmkspfgza7zmf8tfkk88gcf7wse3f346x5qeh4s2fjsf8zcj7zkcqnmq3nwevq68rkp8n3jae8d2r8qmp5c8dp6rzhsnkzx2lhxk4jhtwcnevcuqjv5l63ujac63p34s0lpqq7cxqplptw40z23nzaag0cz6yqdceguu352cc83spfds8esu92t2mukc2l3428sy8lt99fat8hmx7dej5kacuvt5rqz9y4hpjf72ll4ppyyqjvt8lya4vqqn48906ra7rtnh6yljc20dajs44c4m8z6flcjz8srxdpxce8szs7u2ty6gagcjfujzcdda43rk0k8jcta59jrcrxygtztps86cddvjg6rmmcasg30mmgx9d808clkrm0kqranpnr3djrv4qvdhqxn74w3050l7q4j3guv7cmgyt8gefg8zp58nc8zvj67vhqccdqvqqqqqqqqqqpj990s7fz7fpur5rs6wxupkx74kf9n83eslsqj5l0sv6cvj6q82gphgq8xgzh2gv50yzckgxzayxsyqfjllqh2jdg0y6dxxtpvw7dezaum7yscyahyxre33d50jput3jwz24zwpxfudrwn36zrqvy5xg2fcqqyrvaynt8rrcqzwt3lfk92xdln9yh3w9l3r7hnnrulpnvjtzau7sdpl6822ced9ee240am4dwq75vu8l29f8jky86m8epuqe4wge63ue79txmq4vhlzwk758d066xmz3qyqqj3xtvg"}} -``` \ No newline at end of file diff --git a/documentation/cli/03_build.md b/documentation/cli/03_build.md new file mode 100644 index 000000000..78be87ed3 --- /dev/null +++ b/documentation/cli/03_build.md @@ -0,0 +1,61 @@ +--- +id: cli_build +title: leo build +sidebar_label: Build +--- +[general tags]: # (cli, leo_build, build, compile, program) + +## `leo build` + +[Back to Top](#commands) + +To compile your program into Aleo instructions and verify that it builds properly, run: +```bash +leo build +``` + +On invoking the build command, Leo automatically creates a `build/⁠` and `output/`⁠ folder in the project directory. The compiled `.aleo` file is contained in the `build` directory. The `output` directory is used to stored intermediate artifacts from compilation. + +```bash title="console output:" + Leo 2 statements before dead code elimination. + Leo 2 statements after dead code elimination. + Leo The program checksum is: '[...]'. + Leo βœ… Compiled '{PROGRAM_NAME}.aleo' into Aleo instructions. +``` + +### Flags: +``` +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +--private-key + The private key to use for the deployment. Overrides the `PRIVATE_KEY` environment variable. +--network + The network to deploy to. Overrides the `NETWORK` environment variable. +--endpoint + The endpoint to deploy to. Overrides the `ENDPOINT` environment variable. +--devnet + Whether the network is a devnet. If not set, defaults to the `DEVNET` environment variable. +--consensus-heights + Optional consensus heights to use. This should only be set if you are using a custom devnet. +``` + diff --git a/documentation/cli/04_clean.md b/documentation/cli/04_clean.md new file mode 100644 index 000000000..1b7d2f08d --- /dev/null +++ b/documentation/cli/04_clean.md @@ -0,0 +1,16 @@ +--- +id: cli_clean +title: leo clean +sidebar_label: Clean +--- +[general tags]: # (cli, leo_clean, clean) + +To clean the build directory, run: +```bash +leo clean +``` +```bash title="console output:" + Leo 🧹 Cleaned the outputs directory (in "...") + Leo 🧹 Cleaned the build directory (in "...") +``` + diff --git a/documentation/testing/02_debugger.md b/documentation/cli/05_debug.md similarity index 84% rename from documentation/testing/02_debugger.md rename to documentation/cli/05_debug.md index 90499b7cd..2e0a6119a 100644 --- a/documentation/testing/02_debugger.md +++ b/documentation/cli/05_debug.md @@ -1,18 +1,19 @@ --- -id: debugging -title: Debugging Your Code -sidebar_label: Debugging +id: cli_debug +title: leo debug +sidebar_label: Debug --- +[general tags]: # (cli, leo_debug, debug, debugger) -Here are a few techniques to debug your programs. +To start the interactive debugger, run `leo debug` in a Leo project. -## Interactive Debugging +```bash +> leo debug + Leo βœ… Compiled sources for 'workshop' +This is the Leo Interpreter. Try the command `#help`. -Leo ships with an interactive debugger that you can use to step through your programs. - -### Getting Started - -Run through the [tutorial](./../guides/02_debuggin.md) to get familiar with the debugger. +? Command? β€Ί +``` ### Cheatsheet @@ -72,7 +73,4 @@ enter Leo code at the prompt, interpreter state is saved. Input history is available - use the up and down arrow keys. ``` - -### Inspect Compiler Output - - +See [Debugging](./../guides/09_debugging.md) for more details. diff --git a/documentation/cli/06_deploy.md b/documentation/cli/06_deploy.md new file mode 100644 index 000000000..ab45282aa --- /dev/null +++ b/documentation/cli/06_deploy.md @@ -0,0 +1,187 @@ +--- +id: cli_deploy +title: leo deploy +sidebar_label: deploy +--- +[general tags]: # (cli, leo_deploy, deploy, deployment, transaction, program) + +:::note +This command requires having a funded account. +::: + +To deploy the project in the current working directory, run the following command: + +```bash +leo deploy # Defaults to using the private key, network, and endpoint in .env or environment variables +``` + + +```bash title="sample output:" + Leo ... statements before dead code elimination. + Leo ... statements after dead code elimination. + Leo The program checksum is: '[...]'. + Leo βœ… Compiled '{PROGRAM_NAME}.aleo' into Aleo instructions. + +πŸ“’ Using the following consensus heights: 0,2950000,4800000,6625000,6765000,7600000,8365000,9173000,9800000 + To override, pass in `--consensus-heights` or override the environment variable `CONSENSUS_VERSION_HEIGHTS`. + +Attempting to determine the consensus version from the latest block height at {ENDPOINT}... + +πŸ› οΈ Deployment Plan Summary +────────────────────────────────────────────── +πŸ”§ Configuration: + Private Key: {PRIVATE_KEY} + Address: {ADDRESS} + Endpoint: {ENDPOINT} + Network: {NETWORK} + Consensus Version: {CONSENSUS_VERSION} + +πŸ“¦ Deployment Tasks: + β€’ {PROGRAM_NAME}.aleo β”‚ priority fee: 0 β”‚ fee record: no (public fee) + +βš™οΈ Actions: + β€’ Transaction(s) will NOT be printed to the console. + β€’ Transaction(s) will NOT be saved to a file. + β€’ Transaction(s) will be broadcast to {ENDPOINT} + +πŸ”§ Your program '{PROGRAM_NAME}.aleo' has the following constructor. +────────────────────────────────────────────── +constructor: + ... +────────────────────────────────────────────── +Once it is deployed, it CANNOT be changed. + +πŸ“¦ Creating deployment transaction for '{PROGRAM_NAME}.aleo'... + + +πŸ“Š Deployment Summary for '{PROGRAM_NAME}.aleo' +────────────────────────────────────────────── + Total Variables: ... + Total Constraints: ... + Max Variables: 2,097,152 + Max Constraints: 2,097,152 + +πŸ’° Cost Breakdown (credits) + Transaction Storage: ... + Program Synthesis: ... + Namespace: ... + Constructor: ... + Priority Fee: ... + Total Fee: ... +────────────────────────────────────────────── +``` + +See the **[Deploying](./../guides/03_deploying.md)** guide for more details. + + +### Flags: + +#### `--private-key ` +Specifies the private key to use for the deployment. Overrides any `$PRIVATE_KEY` environment variable set manually or in a `.env` file. + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +**Common Endpoints:** + +| Network | Endpoint | +|:---------:|:------:| +| Devnet (local) | https://localhost:3030 | +| Testnet | https://api.explorer.provable.com/v1| +| Mainnet | https://api.explorer.provable.com/v1| + + +#### `--devnet` +Specifies whether the network being deployed to is a devnet. If not set, defaults to the `DEVNET` environment variable. + +:::info +This flag requires a devnet to be running locally. See INSERT DEVNET GUIDE HERE for more information +::: + + +#### `-print` +Prints the transaction to the terminal/stdout in JSON format. + +#### `-broadcast` +Broadcasts the transaction to the network upon successful execution. Without passing this flag, the transaction will just be generated locally. + +#### `--save ` +Saves the transaction to the directory located at the `` path. + +#### `--skip ...` +Skips deployment of any program that contains one of the given substrings, delimited by a space. + +#### `-y` +#### `--yes` +The CLI will ask for manual confirmation on several steps throughout the deployment process. Setting this flag automatically agrees to all confirmations. + +:::warning +Do not use this feature unless you know what you are doing! +::: + +#### `--priority-fees ` +Specifes the priority fee for the deployment transaction(s) delimited by `|` and used in order. The fees are in microcredits and must either be valid `u64` or `default`. Defaults to 0. + +:::tip +1 Credit == 1,000,000 Microcreditss +::: + + +#### `-f ` +#### `--fee-records ` + +Specifes the record(s) to pay for fees privately, delimited by `|` and used in order. The fees must either be valid plaintext, ciphertext, or `default`. If not specified, then transaction fees will be public. + + +#### `--consensus-heights ` +Specifies the consensus heights to use, delimited by `,`. This should only be set if you are using a custom devnet. + +The following will enable Consensus_V0 at block 0, Consensus_V1 at block 1, etc.: +```bash +--consensus-heights 0,1,2,3.... +``` + + +#### `--consensus-version ` +Specifies the consensus version to use. If one is not provided, the CLI will attempt to determine it from the latest block. + +#### `--max-wait ` +Specifies the number of seconds to wait for a block to appear when searching for a transaction. Defaults to 8 seconds. + +#### `--blocks-to-check ` +Specifies the number of blocks to look at when searching for a transaction. Defaults to 12 blocks + +``` +Options: +--base-fees + [UNUSED] Base fees in microcredits, delimited by `|`, and used in order. The fees must either be valid `u64` or `default`. Defaults to automatic calculation. +--skip ... + Skips deployment of any program that contains one of the given substrings. +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +``` + diff --git a/documentation/cli/07_devnet.md b/documentation/cli/07_devnet.md new file mode 100644 index 000000000..eff93c2b2 --- /dev/null +++ b/documentation/cli/07_devnet.md @@ -0,0 +1,78 @@ +--- +id: cli_devnet +title: leo devnet +sidebar_label: Devnet +--- +[general tags]: # (cli, leo_devnet, devnet local_devnet, snarkos) + +## `leo devnet` +[Back to Top](#commands) +:::tip +Use this command to initialize a local devnet +::: + +:::info +The default ENDPOINT for a local devnet is `http://localhost:3030` +::: + +To intialize a local devnet, run the following command: +```bash +leo devnet --snarkos +``` +where `` should be the path to an installed binary of snarkOS. + +If you don't have snarkOS installed, you can do so by passing the `--install` flag, which will install the binary at the path specified above. + +### Flags: +#### `--snarkos ` +Specifies the path to the installed snarkOS binary. + +:::info +This flag is required! +::: + +#### `--snarkos-features ` +Specifies which features of snarkOS to use (e.g. `test_network`) + +#### `--install` +Installs (or reinstalls) snarkOS at the provided `--snarkos` path with the given `--snarkos-features`. + +#### `--snarkos-version ` +Specifies which version of snarkOS to use or install. Defaults to latest version on [crates.io](https://crates.io/crates/snarkos) + +#### `--consensus-heights ` +Optional blocks heights to use for each successive consensus upgrade. Must have `--snarkos-features test_network` enabled as well. + +The following will enable Consensus_V0 at block 0, Consensus_V1 at block 1, etc.: +```bash +--consensus-heights 0,1,2,3.... +``` + +#### `--storage ` +Root directory path for snarkOS ledgers and logs. Defaults to `./` + +#### `--clear-storage` +Clear existing snarkOS ledgers before starting the devnet + + +#### `--network ` +Specifies what the network ID of the devnet will be. + +| ID | Network | +|:---------:|:------:| +| 0 | Mainnet | +| 1 | Testnet (default)| +| 2 | Canary | + +#### `--tmux` +Run devnet nodes in tmux (only available on Unix-based systems) + +#### `--num-validators ` +Number of validators to use in snarkOS. Defaults to 4. + +#### `--num-clients ` +Number of clients to use in snarkOS. Defaults to 2. + +#### `--verbosity ` +Specifies the verbository of snarkOS (0-4). Defaults to 1. + diff --git a/documentation/cli/08_execute.md b/documentation/cli/08_execute.md new file mode 100644 index 000000000..f598fe44e --- /dev/null +++ b/documentation/cli/08_execute.md @@ -0,0 +1,183 @@ +--- +id: cli_execute +title: leo execute +sidebar_label: Execute +--- +[general tags]: # (cli, leo_execute, execute, execution, transaction, transition, transaction_status, async_transition) + +:::note +This command requires having a funded account. +::: + +You can execute a transition function by using the `leo execute` command. This differs from the `leo run` command in that a transaction and proof of execution are produced, and optionally can be broadcasted to the network. + +To execute a Leo transition function with inputs from the command line, run the following command: +```bash +leo execute +``` +where `` is the name of the `transition` or `async transition` function to execute and ``is a list of inputs to the program separated by spaces. + +Under the hood, this command synthesizes the program circuit and generates proving and verifying keys. + + +```bash title="sample output:" + Leo ... statements before dead code elimination. + Leo ... statements after dead code elimination. + Leo The program checksum is: '[...]'. + Leo βœ… Compiled '{PROGRAM_NAME}.aleo' into Aleo instructions. + +πŸ“’ Using the following consensus heights: 0,2950000,4800000,6625000,6765000,7600000,8365000,9173000,9800000 + To override, pass in `--consensus-heights` or override the environment variable `CONSENSUS_VERSION_HEIGHTS`. + +Attempting to determine the consensus version from the latest block height at {ENDPOINT}... + +πŸš€ Execution Plan Summary +────────────────────────────────────────────── +πŸ”§ Configuration: + Private Key: {PRIVATE_KEY} + Address: {ADDRESS} + Endpoint: {ENDPOINT} + Network: {NETWORK} + Consensus Version: {CONSENSUS_VERSION} + +🎯 Execution Target: + Program: {PROGRAM_NAME}.aleo + Function: {FUNCTION_NAME} + Source: remote + +πŸ’Έ Fee Info: + Priority Fee: {PRIORITY_FEE} ΞΌcredits + Fee Record: no (public fee) | {FEE RECORD} + +βš™οΈ Actions: + - Program and its dependencies will be downloaded from the network. + - Transaction will NOT be printed to the console. + - Transaction will NOT be saved to a file. + - Transaction will NOT be broadcast to the network. + +πŸ“Š Execution Summary for {PROGRAM_NAME}.aleo +────────────────────────────────────────────── +πŸ’° Cost Breakdown (credits) + Transaction Storage: ... + On‑chain Execution: ... + Priority Fee: ... + Total Fee: ... +────────────────────────────────────────────── + +➑️ Outputs + + β€’ {OUTPUT_0} + β€’ {OUTPUT_1} + ... +``` + + +See the **[Executing](./../guides/04_executing.md)** guide for more details. + + +### Flags: + +#### `--private-key ` +Specifies the private key to use for the deployment. Overrides any `$PRIVATE_KEY` environment variable set manually or in a `.env` file. + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +**Common Endpoints:** + +| Network | Endpoint | +|:---------:|:------:| +| Devnet (local) | https://localhost:3030 | +| Testnet | https://api.explorer.provable.com/v1| +| Mainnet | https://api.explorer.provable.com/v1| + + +#### `--devnet` +Specifies whether the network being deployed to is a devnet. If not set, defaults to the `DEVNET` environment variable. + +:::info +This flag requires a devnet to be running locally. See INSERT DEVNET GUIDE HERE for more information +::: + + +#### `-print` +Prints the transaction to the terminal/stdout in JSON format. + +#### `-broadcast` +Broadcasts the transaction to the network upon successful execution. Without passing this flag, the transaction will just be generated locally. + +#### `--save ` +Saves the transaction to the directory located at the `` path. + +#### `-y` +#### `--yes` +The CLI will ask for manual confirmation on several steps throughout the deployment process. Setting this flag automatically agrees to all confirmations. + +:::warning +Do not use this feature unless you know what you are doing! +::: + +#### `--priority-fees ` +Specifes the priority fee for the deployment transaction(s) delimited by `|` and used in order. The fees are in microcredits and must either be valid `u64` or `default`. Defaults to 0. + +:::tip +1 Credit == 1,000,000 Microcreditss +::: + + +#### `-f ` +#### `--fee-records ` + +Specifes the record(s) to pay for fees privately, delimited by `|` and used in order. The fees must either be valid plaintext, ciphertext, or `default`. If not specified, then transaction fees will be public. + + +#### `--consensus-heights ` +Specifies the consensus heights to use, delimited by `,`. This should only be set if you are using a custom devnet. + +The following will enable Consensus_V0 at block 0, Consensus_V1 at block 1, etc.: +```bash +--consensus-heights 0,1,2,3.... +``` + + +#### `--consensus-version ` +Specifies the consensus version to use. If one is not provided, the CLI will attempt to determine it from the latest block. + +#### `--max-wait ` +Specifies the number of seconds to wait for a block to appear when searching for a transaction. Defaults to 8 seconds. + +#### `--blocks-to-check ` +Specifies the number of blocks to look at when searching for a transaction. Defaults to 12 blocks + +``` +Options: +--base-fees + [UNUSED] Base fees in microcredits, delimited by `|`, and used in order. The fees must either be valid `u64` or `default`. Defaults to automatic calculation. +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +``` + diff --git a/documentation/cli/09_new.md b/documentation/cli/09_new.md new file mode 100644 index 000000000..9351cf4c6 --- /dev/null +++ b/documentation/cli/09_new.md @@ -0,0 +1,16 @@ +--- +id: cli_new +title: leo new +sidebar_label: New +--- +[general tags]: # (cli, leo_new, new, new_project) + +To create a new project, run: +```bash +leo new +``` + +Valid project names are snake_case: lowercase letters and numbers separated by underscores. +This command will create a new directory with the given project name. + +See [Project Layout](./../language/01_layout.md) for more details . diff --git a/documentation/cli/10_query.md b/documentation/cli/10_query.md new file mode 100644 index 000000000..ff028ee06 --- /dev/null +++ b/documentation/cli/10_query.md @@ -0,0 +1,290 @@ +--- +id: cli_query +title: leo query +sidebar_label: Query +--- +[general tags]: # (cli, leo_query, query, block, transaction, program, stateroot, committee, mempool, peers, snarkOS, mapping) + +The `leo query` command is used to get data from a network supporting the canonical `snarkOS` endpoints. + + +## Subcommands +* [`block`](#leo-query-block) - Query block information. +* [`transaction`](#leo-query-transaction) - Query transaction information. +* [`program`](#leo-query-program) - Query program source code and live mapping values. +* [`stateroot`](#leo-query-stateroot) - Query the latest stateroot. +* [`committee`](#leo-query-committee) - Query the current committee. +* [`mempool`](#leo-query-mempool) - Query transactions and transmissions from the memory pool. +* [`peers`](#leo-query-peers) - Query peer information. + +  + +--- + + +### `leo query block` + +To fetch blocks from a given network, run the following command +```bash +leo query +``` +where `` is either a specific block height or block hash. The block will be returned in JSON format. + +For example, you can fetch the Mainnet genesis block by running either of the following commands: +```bash +leo query block 0 --network mainnet --endpoint https://api.explorer.provable.com/v1 +``` +```bash +leo query block ab1sm6kyqle2ftg4z8gegafqrjy0jwjhzu6fmy73726dgszrtxhxvfqha0eee --network mainnet --endpoint https://api.explorer.provable.com/v1 +``` + + + +### Flags: + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + + +#### `--latest` +#### `-l` +Queries the latest block. + +```bash title="Example:" +leo query block --latest +``` + + +#### `--latest-hash` +Queries the hash of the latest block. + +```bash title="Example:" +leo query block --latest-hash +``` + + +#### `--latest-height` +Queries the height of the latest block + +```bash title="Example:" +leo query block --latest-height +``` + +#### `--range ` +#### `-r ` +Queries up to 50 consecutive blocks. + +```bash title="Example:" +leo query block --range +``` + + +#### `--transactions` +#### `-t` +Queries all transactions at the specified block height +```bash title="Example:" +leo query block --transactions +``` + + +#### `--to-height` +Queries the block height corresponding to a hash value +```bash title="Example:" +leo query block --to-height +``` + +--- + +### `leo query transaction` + +To fetch a specific transaction from a given network, run the following command: + +```bash +leo query transaction +``` +where `` is the ID of the transaction. The transaction will be returned in JSON format. + +### Flags: + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + + +#### `--confirmed` +#### `-c` +Returns information (including details about onchain execution) about the queried transaction if it was confirmed. + + +#### `--unconfirmed` +#### `-u` +Queries the original (unconfirmed) transaction. + + +#### `--from-io ` +Get the ID of the transaction that an input or output ID occurred in. +```bash title="Example:" +leo query transaction --from-io +``` + + +#### `--from-transition ` +Get the ID of the transaction containing the specified transition. + +```bash title="Example:" +leo query transaction --from-transition +``` + + +#### `--from-program ` +Get the ID of the transaction that the specified program was deployed in. +```bash title="Example:" +leo query transaction --from-program +``` + +--- + +### `leo query program` + +To fetch a specific program from a given network, run the following command: + +```bash +leo query program +``` + +You can also use this to query specific mappings and mapping values from a given program. For example, if you wanted to query your public balance of Aleo credits: + +```bash +leo query program credits.aleo --mapping-value account +``` + + +### Flags: + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + + +#### `--mappings` +Lists all mappings defined in the latest deployed edition of the program. + + +#### `--mapping-value ` +Get the value corresponding to the specified mapping and key. Will return `null` if key is not present in mapping. + +#### `--edition ` +An optional edition to query for when fetching the program source. If not specified, the latest edition will be used. + +The edition of the program is set to `0` upon initial deployment and is incremented by `1` each time the program is upgraded. See the **[Upgrading Programs](./../guides/10_program_upgradability.md)** guide for more details. + + +--- + +### `leo query stateroot` + +This command queries the latest stateroot of a given network. + +### Flags: + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +--- + +### `leo query committee` + +This command queries the current validator committee for a given network. + +### Flags: + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +--- + +### `leo query mempool` + +This command queries transactions and transmissions from the memory pool for a node on a given network. + +:::note +This command can only be run with a custom endpoint. Using the official Provable API endpoint will fail. +::: + +To query transactions: +```bash +leo query mempool --transactions +``` + +To query transmissions: +```bash +leo query mempool --transmissions +``` + + +### Flags: + +#### `--transactions` +Queries the transactions in the memory pool. + + +#### `--transmissions` +Queries the transactions in the memory pool. + + + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +--- + +### `leo query peers` + +This command queries peer information for a node on a given network. + +:::note +This command can only be run with a custom endpoint. Using the official Provable API endpoint will fail. +::: + +### Flags: + +#### `--metrics` +#### `-m` +Queries all peer metrics + + +#### `--count` +#### `-c` +Queries the count of all participating peers + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + + + diff --git a/documentation/cli/11_remove.md b/documentation/cli/11_remove.md new file mode 100644 index 000000000..8dc457916 --- /dev/null +++ b/documentation/cli/11_remove.md @@ -0,0 +1,24 @@ +--- +id: cli_remove +title: leo remove +sidebar_label: Remove +--- +[general tags]: # (cli, leo_remove, remove_dependency, dependency, dependency_management, imports) + +To remove a dependency from your project, run the following command: + +```bash +leo remove +``` +where `` is the name of the imported program. + +See the **[Dependency Management](./../guides/02_dependencies.md)** guide for more details. + +### Flags: + +#### `--all` +Removes all dependencies (or dev dependencies, if used with --dev). + +#### `-dev` +Removes dev dependencies. + diff --git a/documentation/cli/12_run.md b/documentation/cli/12_run.md new file mode 100644 index 000000000..abb22acf4 --- /dev/null +++ b/documentation/cli/12_run.md @@ -0,0 +1,83 @@ +--- +id: cli_run +title: leo run +sidebar_label: Run +--- +[general tags]: # (cli, leo_run, run, transition, async_transition) + +:::tip +Use this command to run your program before [**executing**](#leo-execute) it. +::: + +You can run a transition function by using the `leo run` command. This will simply run the specified transition function with the provided inputs and show what the produced output will be. It will NOT generate the zero-knowledge proof of execution or the transaction, and nothing will be run onchain. For that, please see the `leo execute` command. + +To run a Leo transition function with inputs from the command line, run the following command: +```bash +leo run +``` + +where `` is the name of the `transition` or `async transition` function to run and `` is a list of inputs to the program separated by spaces. + +This command does not synthesize the program circuit or generate proving and verifying keys. + +```bash title="sample output:" + Leo ... statements before dead code elimination. + Leo ... statements after dead code elimination. + Leo The program checksum is: '[...]'. + Leo βœ… Compiled '{PROGRAM_NAME}.aleo' into Aleo instructions. + +β›“ Constraints + + β€’ '{PROGRAM_NAME}.aleo/{FUNCTION_NAME}' - ... constraints (called 1 time) + +➑️ Outputs + + β€’ {OUTPUT_0} + β€’ {OUTPUT_1} + ... +``` + +If one or more of your inputs are negatives, and consequently begin with a `-`, +you may separate the inputs with a `--` so that the command line parser +won't attempt to parse them as options: +```bash +leo run -- -- ... +``` + +### Flags: +``` +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +--private-key + The private key to use for the deployment. Overrides the `PRIVATE_KEY` environment variable. +--network + The network to deploy to. Overrides the `NETWORK` environment variable. +--endpoint + The endpoint to deploy to. Overrides the `ENDPOINT` environment variable. +--devnet + Whether the network is a devnet. If not set, defaults to the `DEVNET` environment variable. +--consensus-heights + Optional consensus heights to use. This should only be set if you are using a custom devnet. +``` + + diff --git a/documentation/cli/13_test.md b/documentation/cli/13_test.md new file mode 100644 index 000000000..85d9a4e8e --- /dev/null +++ b/documentation/cli/13_test.md @@ -0,0 +1,44 @@ +--- +id: cli_test +title: leo test +sidebar_label: Test +--- +[general tags]: # (cli, leo_test, testing) + +This command runs all the test cases specified in the Leo file in `tests/`. + +If you want to run a specific set of tests, run the following command: +```bash +leo test +``` +where `` is the string to match against the qualified name of each test. + +Check out the [**Testing**](./../guides/08_testing.md) guide for more information. + + +### Flags: +``` +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +``` + diff --git a/documentation/cli/14_update.md b/documentation/cli/14_update.md new file mode 100644 index 000000000..1c8a7df76 --- /dev/null +++ b/documentation/cli/14_update.md @@ -0,0 +1,36 @@ +--- +id: cli_update +title: leo update +sidebar_label: Update +--- +[general tags]: # (cli, leo_update, versioning) + +To download and install the latest Leo version run: + +```bash +leo update +``` + +```bash title="console output:" +Checking target-arch... aarch64-apple-darwin +Checking current version... v3.1.0 +Checking latest released version... v3.1.0 + Leo +Leo is already on the latest version +``` + +If you'd like to install a specific version of Leo, you can do so by passing the `--name` flag: + +```bash +leo update --name v3.0.0 +``` + +### Flags: +#### `-l` +#### `--list` +Lists all available versions of Leo. + +#### `-n` +#### `--name` +An optional release name if you wish to install a specific version of Leo. By default, the command will look for the latest release. + diff --git a/documentation/cli/15_upgrade.md b/documentation/cli/15_upgrade.md new file mode 100644 index 000000000..23b396382 --- /dev/null +++ b/documentation/cli/15_upgrade.md @@ -0,0 +1,123 @@ +--- +id: cli_upgrade +title: leo upgrade +sidebar_label: Upgrade +--- +[general tags]: # (cli, leo_upgrade, upgrade, program) + +Upgrades a program that is already deployed on the network. + +See the **[Upgrading Programs](./../guides/10_program_upgradability.md)** guide for more details. + + +### Flags: + +#### `--private-key ` +Specifies the private key to use for the deployment. Overrides any `$PRIVATE_KEY` environment variable set manually or in a `.env` file. + +#### `--network ` +Specifies the network to deploy to. Overrides any `NETWORK` environment variable set manually or in a `.env` file. Valid network names are `testnet`, `mainnet`, and `canary`. + + +#### `--endpoint ` +The endpoint to deploy to. Overrides any `ENDPOINT` environment variable set manually or in a `.env` file. + +**Common Endpoints:** + +| Network | Endpoint | +|:---------:|:------:| +| Devnet (local) | https://localhost:3030 | +| Testnet | https://api.explorer.provable.com/v1| +| Mainnet | https://api.explorer.provable.com/v1| + + +#### `--devnet` +Specifies whether the network being deployed to is a devnet. If not set, defaults to the `DEVNET` environment variable. + +:::info +This flag requires a devnet to be running locally. See INSERT DEVNET GUIDE HERE for more information +::: + + +#### `-print` +Prints the transaction to the terminal/stdout in JSON format. + +#### `-broadcast` +Broadcasts the transaction to the network upon successful execution. Without passing this flag, the transaction will just be generated locally. + +#### `--save ` +Saves the transaction to the directory located at the `` path. + +#### `-y` +#### `--yes` +The CLI will ask for manual confirmation on several steps throughout the deployment process. Setting this flag automatically agrees to all confirmations. + +:::warning +Do not use this feature unless you know what you are doing! +::: + +#### `--priority-fees ` +Specifes the priority fee for the deployment transaction(s) delimited by `|` and used in order. The fees are in microcredits and must either be valid `u64` or `default`. Defaults to 0. + +:::tip +1 Credit == 1,000,000 Microcreditss +::: + + +#### `-f ` +#### `--fee-records ` + +Specifes the record(s) to pay for fees privately, delimited by `|` and used in order. The fees must either be valid plaintext, ciphertext, or `default`. If not specified, then transaction fees will be public. + + +#### `--consensus-heights ` +Specifies the consensus heights to use, delimited by `,`. This should only be set if you are using a custom devnet. + +The following will enable Consensus_V0 at block 0, Consensus_V1 at block 1, etc.: +```bash +--consensus-heights 0,1,2,3.... +``` + + +#### `--consensus-version ` +Specifies the consensus version to use. If one is not provided, the CLI will attempt to determine it from the latest block. + +#### `--max-wait ` +Specifies the number of seconds to wait for a block to appear when searching for a transaction. Defaults to 8 seconds. + +#### `--blocks-to-check ` +Specifies the number of blocks to look at when searching for a transaction. Defaults to 12 blocks + +``` +Options: +--base-fees + [UNUSED] Base fees in microcredits, delimited by `|`, and used in order. The fees must either be valid `u64` or `default`. Defaults to automatic calculation. +--skip ... + Skips the upgrade of any program that contains one of the given substrings. +--offline + Enables offline mode. +--enable-ast-spans + Enable spans in AST snapshots. +--enable-dce + Enables dead code elimination in the compiler. +--conditional-block-max-depth + Max depth to type check nested conditionals. [default: 10] +--disable-conditional-branch-type-checking + Disable type checking of nested conditional branches in finalize scope. +--enable-initial-ast-snapshot + Write an AST snapshot immediately after parsing. +--enable-all-ast-snapshots + Writes all AST snapshots for the different compiler phases. +--ast-snapshots ... + Comma separated list of passes whose AST snapshots to capture. +--build-tests + Build tests along with the main program and dependencies. +--no-cache + Don't use the dependency cache. +--no-local + Don't use the local source code. +``` + + + + diff --git a/documentation/sdk/00_sdk_overview.md b/documentation/deprecated/sdk/00_sdk_overview.md similarity index 100% rename from documentation/sdk/00_sdk_overview.md rename to documentation/deprecated/sdk/00_sdk_overview.md diff --git a/documentation/sdk/python/00_aleo_sdk.md b/documentation/deprecated/sdk/python/00_aleo_sdk.md similarity index 100% rename from documentation/sdk/python/00_aleo_sdk.md rename to documentation/deprecated/sdk/python/00_aleo_sdk.md diff --git a/documentation/sdk/python/01_zkml_transpiler.md b/documentation/deprecated/sdk/python/01_zkml_transpiler.md similarity index 100% rename from documentation/sdk/python/01_zkml_transpiler.md rename to documentation/deprecated/sdk/python/01_zkml_transpiler.md diff --git a/documentation/sdk/typescript/00_sdk_overview.md b/documentation/deprecated/sdk/typescript/00_sdk_overview.md similarity index 100% rename from documentation/sdk/typescript/00_sdk_overview.md rename to documentation/deprecated/sdk/typescript/00_sdk_overview.md diff --git a/documentation/sdk/typescript/01_account.md b/documentation/deprecated/sdk/typescript/01_account.md similarity index 100% rename from documentation/sdk/typescript/01_account.md rename to documentation/deprecated/sdk/typescript/01_account.md diff --git a/documentation/sdk/typescript/02_aleo_network_client.md b/documentation/deprecated/sdk/typescript/02_aleo_network_client.md similarity index 100% rename from documentation/sdk/typescript/02_aleo_network_client.md rename to documentation/deprecated/sdk/typescript/02_aleo_network_client.md diff --git a/documentation/sdk/typescript/03_development_client.md b/documentation/deprecated/sdk/typescript/03_development_client.md similarity index 100% rename from documentation/sdk/typescript/03_development_client.md rename to documentation/deprecated/sdk/typescript/03_development_client.md diff --git a/documentation/sdk/wasm/00_wasm_installation.md b/documentation/deprecated/sdk/wasm/00_wasm_installation.md similarity index 100% rename from documentation/sdk/wasm/00_wasm_installation.md rename to documentation/deprecated/sdk/wasm/00_wasm_installation.md diff --git a/documentation/sdk/wasm/01_nodejs.md b/documentation/deprecated/sdk/wasm/01_nodejs.md similarity index 100% rename from documentation/sdk/wasm/01_nodejs.md rename to documentation/deprecated/sdk/wasm/01_nodejs.md diff --git a/documentation/sdk/wasm/02_browser_multi_thread.md b/documentation/deprecated/sdk/wasm/02_browser_multi_thread.md similarity index 100% rename from documentation/sdk/wasm/02_browser_multi_thread.md rename to documentation/deprecated/sdk/wasm/02_browser_multi_thread.md diff --git a/documentation/getting_started/01_installation.md b/documentation/getting_started/01_installation.md index e72211567..b56507702 100644 --- a/documentation/getting_started/01_installation.md +++ b/documentation/getting_started/01_installation.md @@ -3,6 +3,7 @@ id: installation title: Installation sidebar: Installation --- +[general tags]: # (installation, install_leo) import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -19,54 +20,63 @@ values={[ { label: 'Pre-Built Binaries', value: 'prebuilt' }, { label: 'Build from Source', value: 'source' }, ]}> - -

1. Install Cargo

-

The easiest way to install Cargo is to install the latest stable release of Rust: bit.ly/start-rust

-

2. Install Leo

- 
cargo install leo-lang
-

This will generate the executable at ~/.cargo/bin/leo.

- - -

Download and install Leo with the official pre-built binaries.

-

For MacOS (Apple Silicon)

- -

Installation:

-
    -
  1. Extract the .zip file.
    2. -
  2. Open a terminal and navigate to the extracted directory.
    3. -
  3. Run chmod +x leo to make the file executable.
    4. -
  4. Move leo to /usr/local/bin to use it system-wide.
    5. - 
    mv leo /usr/local/bin
    -
  5. Run leo --version to confirm installation.
    6. -
-

For Other Platforms

- - - -

Install from Source

-

To use the latest Leo features, install the Leo source code from GitHub.

-

1. Install the Prerequisites

- -

Verify Installation

- 
git --version
- 
cargo --version
-

2. Build Leo from Source Code

- 
# Download the source code
+
+
+### 1. Install Cargo
+The easiest way to install Cargo is to install the latest stable release of [Rust](https://www.rust-lang.org/tools/install).
+### 2. Install Leo
+```bash
+cargo install leo-lang
+```
+This will generate the executable at `~/.cargo/bin/leo`.
+
+
+Download and install Leo with the official pre-built binaries.
+
+### For MacOS (Apple Silicon):
+  - **[Download Leo for Apple Silicon (MacOS)](https://github.com/ProvableHQ/leo/releases/latest/download/leo.zip)**
+  - This will download a `.zip` file containing a **Unix Executable File**.
+#### Installation
+  1. Extract the `.zip` file
+  2. Open a terminal land navigate to the extracted directory.
+  3. Run `chmod +x leo` to make the file executable
+  4. Move `leo` to `/usr/local/bin` to use it system wide.
+
+          mv leo /usr/local/bin
+
+  5. Run `leo --version` to confirm installation
+
+  ### For Other Platforms:
+   - **[Browse all Leo releases](https://github.com/ProvableHQ/leo/releases)**
+
+
+
+
+### 1. Install the Prerequisites
+ - **Install [Git](https://git-scm.com/downloads)**
+ - **Install [Rust](https://www.rust-lang.org/tools/install)**
+ 
+#### Verify Installation
+```bash
+git --version
+```
+```bash
+cargo --version
+```
+### 2. Build Leo from Source Code
+```bash
+# Download the source code 
 git clone https://github.com/ProvableHQ/leo
 cd leo
 # Build and install
-cargo install --path .
-

This will generate the executable at ~/.cargo/bin/leo.

-

To use Leo, run:

- 
leo
- +cargo install --path . +``` +This will generate the executable at `~/.cargo/bin/leo`. + +#### To use Leo, run: +```bash +leo +``` + diff --git a/documentation/getting_started/02_ide.md b/documentation/getting_started/02_ide.md index 9ca1daf3c..c670fb0d8 100644 --- a/documentation/getting_started/02_ide.md +++ b/documentation/getting_started/02_ide.md @@ -3,6 +3,7 @@ id: ide title: Your Development Environment sidebar_label: Dev Env --- +[general tags]: # (playground, ide, plugin) Developers can choose from a wide variety of development environments. @@ -23,6 +24,22 @@ Developers may find the generating transactions is slower in the browser. This i The Leo team also maintains plugin for a number of different edits. If you do not see your favorite editor on this list, please reach out on [GitHub](https://github.com/ProvableHQ/leo/issues/new). +### VS Code + +[//]: # (![](./images/vscode.png)) +Download the editor here: https://code.visualstudio.com/download. + +#### Install + +1. Install [Leo for VSCode](https://marketplace.visualstudio.com/items?itemName=aleohq.leo-extension) from VSCode marketplace. +2. The correct extension ID is `aleohq.leo-extension`, and the description should state "the official VSCode extension for Leo". + +#### Usage + +1. Open `VSCode`. +2. Go to Settings > Extensions or use the left side panel Extensions button to enable the Leo plugin. + + ### Sublime Text [//]: # (![](./images/sublime.png) ) @@ -41,20 +58,6 @@ Follow these steps to toggle the `Leo` syntax highlighting, hover, and tokens. 1. Open `Sublime Text`. 2. From Settings > Select Color Scheme... > LSP-leo -### VS Code - -[//]: # (![](./images/vscode.png)) -Download the editor here: https://code.visualstudio.com/download. - -#### Install - -1. Install [Leo for VSCode](https://marketplace.visualstudio.com/items?itemName=aleohq.leo-extension) from VSCode marketplace. -2. The correct extension ID is `aleohq.leo-extension`, and the description should state "the official VSCode extension for Leo". - -#### Usage - -1. Open `VSCode`. -2. Go to Settings > Extensions or use the left side panel Extensions button to enable the Leo plugin. ### Intellij diff --git a/documentation/getting_started/03_hello.md b/documentation/getting_started/03_hello.md index aaeab9843..2ad686060 100644 --- a/documentation/getting_started/03_hello.md +++ b/documentation/getting_started/03_hello.md @@ -3,6 +3,7 @@ id: hello title: Hello, Leo sidebar_label: Hello, Leo --- +[general tags]: # (hello_leo, starter_project) ## Initialize the project @@ -20,71 +21,43 @@ hello/ β”œβ”€β”€ .gitignore # A default `.gitignore` file for Leo projects β”œβ”€β”€ .env # The environment, containing the `NETWORK` and `PRIVATE_KEY` variables. β”œβ”€β”€ program.json # The manifest for the Leo project +β”œβ”€β”€ tests/ + └── test_hello.leo # The Leo source code for unit tests └── src/ └── main.leo # The Leo source code ``` -## Build and Run - -Now let's compile the program. -``` -leo build -``` - -On invoking the build command, Leo automatically creates a `/build⁠` and `output/`⁠ folder in the project directory. The compiled code is contained in the `build` directory. `output` is used to stored intermediate artifacts from compilation. - - -The `leo run` command will compile and run the program. -In your terminal, run: -```bash -leo run main 1u32 2u32 -``` - -```bash title="console output:" -Leo Compiled 'main.leo' into Aleo instructions - -β›“ Constraints - β€’ 'hello.aleo/main' - 33 constraints (called 1 time) - -➑️ Output - β€’ 3u32 - -Leo βœ… Finished 'hello.aleo/main' (in "/hello/build") -``` - -Congratulations! You've ran your first Leo program. ## Unpacking the Project -Let's go through the project. - ### The Manifest -**program.json** is the Leo manifest file that configures our package. +**program.json** is the Leo manifest file that configures the package. ```json title="program.json" { "program": "hello.aleo", "version": "0.1.0", "description": "", "license": "MIT", - "dependencies": null + "dependencies": null, + "dev_dependencies": null } ``` -The program ID in `program` is the official name that other developers will be able to look up after the program has been deployed to a network. -```json - "program": "hello.aleo", -``` +The program ID in `program` is the official name that other developers will be able to look up after the program has been deployed to a network. This must be the same as the name of your program in `main.leo`, or compilation will fail. + -Dependencies will be added to the field of the same name, as they are added. The dependencies are also pegged in the **leo.lock** file. +Dependencies will be added to the field of the same name, as they are imported. Dependencies that are only used during development and not in production will be added to the `dev_dependencies` field. ### The Code -Open up **src/main.leo**. -The **main.leo** file is the entry point of a Leo project. It often contains a function named `main`. +The `src/main.leo` file is the entry point of a Leo project. It initially contains a function named `main`. Let's break down the structure of a Leo file. ```leo title="src/main.leo" showLineNumbers // The 'hello' program. program hello.aleo { + @noupgrade + async constructor() {} + transition main(public a: u32, b: u32) -> u32 { let c: u32 = a + b; return c; @@ -92,8 +65,7 @@ program hello.aleo { } ``` -`program hello.aleo {` defines the name of the [program](./../language/02_structure.md#program-scope) inside the Leo file. -The program ID must match the `program.json` manifest file. +The keyword `program` indicates the name of the [program](./../language/02_structure.md#program-scope) inside the Leo file. In this case, it is `hello.aleo`. As mentioned before, this program name must match the one in the `program.json` manifest file. The keyword `transition` indicates a [transition](./../language/02_structure.md#transition-function) function definition in Leo. The `main` transition takes an input `a` with type `u32` and `public` visibility, and an input `b` with type `u32` and `private` visibility (by default). @@ -120,57 +92,81 @@ Leo will check that `c`'s type matches the function return type `u32`. return c; ``` -Now let us use the Leo CLI and see what other commands we can run on our program. - -## Step by step +There is an additional function called a `constructor`. This is a special function that helps enable program upgradability, which allows you to modify some of the logic and contents of a program after you've already deployed it onchain. -### 1. Clean -First, remove all build files with: -```bash -leo clean +```leo +@noupgrade +async constructor() {} ``` -```bash title="console output:" - Leo cleaned the build directory (in "/build/") -``` +The constructor acts as a gatekeeper for your program; the logic in the function gets run before every deployment and upgrade, and governs who and how this program can be deployed and modified. -### 2. Update -The `leo update` command updates the Leo compiler to the latest version. -```bash -leo update -``` -```bash title="console output:" - Leo βœ… Updated to version 1.12.0 +:::note +All programs must have an explicitly declared constructor function. +::: + +For now, we'll leave it as is, which will prevent upgrades from occurring. For more details on how program upgradability works, and different patterns for upgrading your programs, check out [Upgrading Programs](./../guides/10_program_upgradability.md). + + +Now let's compile and run the program. + +## Build and Run + +To compile the program, run: +``` +leo build ``` + +On invoking the build command, Leo automatically creates a `build/⁠` and `output/`⁠ folder in the project directory. The compiled code is contained in the `build` directory. The `output` directory is used to stored intermediate artifacts from compilation. -### 3. Execute -The `leo execute` command executes the Leo program and outputs a transaction object +The `leo run` command will both compile and run the specified function program. +In your terminal, run: ```bash -leo execute main 1u32 2u32 +leo run main 1u32 2u32 ``` ```bash title="console output:" - Leo βœ… Compiled 'main.leo' into Aleo instructions + Leo 2 statements before dead code elimination. + Leo 2 statements after dead code elimination. + Leo The program checksum is: '[212u8, 91u8, ... , 107u8]'. + Leo βœ… Compiled 'hello.aleo' into Aleo instructions. β›“ Constraints - β€’ 'hello.aleo/main' - 33 constraints (called 1 time) + + β€’ 'hello.aleo/main' - 33 constraints (called 1 time) ➑️ Output + β€’ 3u32 - - {"type":"execute","id":"at1 ... (transaction object truncated for brevity) - - Leo βœ… Executed 'hello.aleo/main' (in "/hello/build") + + Leo βœ… Finished 'hello.aleo/main' (in "./hello/build") +``` + +## Deploying and Executing +Running programs locally is great, but you'll likely want to actually deploy your programs and execute functions onchain. To do this, you'll need to use `leo deploy` for deployment and `leo execute` to execute functions and generate the transaction containing the requisite metadata and zero-knowledge proofs. + +We have dedicated guides for both [Deploying](./../guides/03_deploying.md) and [Executing](./../guides/04_executing.md), so please check those out for more information! + + +## Clean +Finally, you can remove all build files and outputs with: +```bash +leo clean ``` -The `leo execute` command will attempt to verify a proof only if all previous steps completed successfully. Under the hood, the Leo [CLI](./../cli/00_overview.md) will check for existing `.prover` file to constructing proof, the `.verifier` file to verify proof and the `.avm` file containing the program's bytecode in the **build/build** directory before running each command. This ensures that we don't run unnecessary commands. +```bash title="console output:" +Leo 🧹 Cleaned the outputs directory ./hello/outputs +Leo 🧹 Cleaned the build directory ./hello/build +``` -You'll notice that running `leo execute` produces a JSON object. This is a [`Transaction`](https://developer.aleo.org/concepts/fundamentals/transactions) that can be broadcast to the Aleo network. ## Next Steps To learn more about the Leo language and its syntax, start [here](./../language/00_overview.md). To learn more about how to use the Leo CLI, start [here](./../cli/00_overview.md). + +To get started with some sample projects, check out the **Leo By Example** section. + diff --git a/documentation/guides/00_overview.md b/documentation/guides/00_overview.md index a32b740c2..8140d85c6 100644 --- a/documentation/guides/00_overview.md +++ b/documentation/guides/00_overview.md @@ -3,9 +3,30 @@ id: overview title: Overview sidebar_label: Overview --- +[general tags]: # (guides) -There is a lot to learn about Leo! To help tame the complexity, we've put together some explainers that you may find helpful. +There's a lot to learn about Leo! To help tame the complexity, we've put together some explainers that you may find helpful. -- [**The Asynchronous Programming Model**](./01_async.md) - Coming soon! +## Basic: +- [**The Asynchronous Programming Model**](./01_async.md) - Learn the fundamentals of the offchain/onchain computation model of Aleo. + +- [**Dependency Management**](./02_dependencies.md) - Learn how to efficiently manage your dependencies. + +- [**Deploy Your Programs**](./03_deploying.md) - Learn how to deploy your programs to different networks. + +- [**Executing Your Programs**](./04_executing.md) - Learn how to execute functions on deployed programs. + +- [**Signing and Verifying**](./05_signing.md) - Learn how to sign and verify data. + +- [**Querying the Network**](./06_query.md) - Learn how to query different metadata from the network. + + +## Advanced +- [**Running a Devnet**](./07_devnet.md) - Learn how to spin up a local development network. + +- [**Testing, Testing, 123**](./08_testing.md) - Learn how to take advantage of the various tools for Leo testing. + +- [**Debuggin' Out**](./09_debugging.md) - Learn how to use Leo's interactive debugger. + +- [**Upgrading Programs**](./10_program_upgradability.md) - Coming soon! -- [**Debuggin' Out**](./02_debuggin.md) - Learn how to use Leo's interactive debugger. diff --git a/documentation/guides/01_async.md b/documentation/guides/01_async.md index 1be7b6000..ba22ea1a0 100644 --- a/documentation/guides/01_async.md +++ b/documentation/guides/01_async.md @@ -3,6 +3,7 @@ id: async title: The Asynchronous Programming Model sidebar_label: Async Model --- +[general tags]: # (guides, async, async_transition, async_function, future, program) ## Background diff --git a/documentation/cli/04_dependencies.md b/documentation/guides/02_dependencies.md similarity index 95% rename from documentation/cli/04_dependencies.md rename to documentation/guides/02_dependencies.md index 6239b6f25..7a1683c06 100644 --- a/documentation/cli/04_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -3,7 +3,9 @@ id: dependencies title: Dependency Management sidebar_label: Dependency Management --- -## Leo imports +[general tags]: # (guides, dependency, dependency_management, imports, program) + +## Leo Imports In your `main.leo` file, specify any imported dependencies using the `import` keyword before the program declaration: ```leo import credits.aleo; diff --git a/documentation/cli/01_deploying.md b/documentation/guides/03_deploying.md similarity index 98% rename from documentation/cli/01_deploying.md rename to documentation/guides/03_deploying.md index 34afa30e0..d6292248a 100644 --- a/documentation/cli/01_deploying.md +++ b/documentation/guides/03_deploying.md @@ -1,9 +1,9 @@ --- id: deploy -title: Deploy and Upgrade Your Programs -sidebar_label: Deploy and Upgrade +title: Deploying Your Programs +sidebar_label: Deploying --- - +[general tags]: # (guides, deploy, deployment, program) The `leo deploy` command is used for deploying Leo program to a local devnet, Testnet, or Mainnet. The `leo upgrade` command is used for upgrading an existing Leo program on the network. @@ -215,7 +215,7 @@ Leo will: If your program is already deployed, you can upgrade it using the `leo upgrade` command. The upgrade will only work if your program is upgradable, meaning it has a constructor that allows for upgrades. -See the [Upgradability Guide](../guides/03_program_upgradability.md) for more details on how to make your program upgradable. +See the [Upgradability Guide](../guides/10_program_upgradability.md) for more details on how to make your program upgradable. ## Options and Environment Variables diff --git a/documentation/guides/04_executing.md b/documentation/guides/04_executing.md new file mode 100644 index 000000000..2e764fcf3 --- /dev/null +++ b/documentation/guides/04_executing.md @@ -0,0 +1,75 @@ +--- +id: execute +title: Executing Your Programs +sidebar_label: Executing +--- + +[general tags]: # (guides,execute, execution, transaction, transition, transaction_status, async_transition) + +The `leo execute` command executes the Leo program and outputs a transaction object +```bash +leo execute ... +``` + +Optionally, you can execute a function in a remote Leo program by using +```bash +leo execute .aleo/ ... +``` + +If executing a function from a local program, the `leo execute` command will first build/compile that program: + +```bash title="console output:" + Leo 2 statements before dead code elimination. + Leo 2 statements after dead code elimination. + Leo The program checksum is: '[212u8, 91u8, ... , 107u8]'. + Leo βœ… Compiled 'hello.aleo' into Aleo instructions. + +``` +It will then print out the summary of the execution plan with +```bash +πŸš€ Execution Plan Summary +────────────────────────────────────────────── +πŸ”§ Configuration: + Private Key: APrivateKey1zkp... + Address: aleo1... + Endpoint: https://api.explorer.provable.com/v1 + Network: + Consensus Version: 9 + +🎯 Execution Target: + Program: + Function: + Source: + +πŸ’Έ Fee Info: + Priority Fee: 0 ΞΌcredits + Fee Record: no (public fee) + +βš™οΈ Actions: + - Transaction will NOT be printed to the console. + - Transaction will NOT be saved to a file. + - Transaction will NOT be broadcast to the network. +``` + +Finally, an execution cost breakdown will be printed alongside any outputs from the function itself. +```bash +πŸ“Š Execution Summary for +────────────────────────────────────────────── +πŸ’° Cost Breakdown (credits) + Transaction Storage: 0.001316 + On‑chain Execution: 0.000000 + Priority Fee: 0.000000 + Total Fee: 0.001316 +────────────────────────────────────────────── + +➑️ Output + + β€’ + β€’ + ... +``` + +Under the hood, `leo execute` produces a JSON object. This is a [`Transaction`](https://developer.aleo.org/concepts/fundamentals/transactions) that can be broadcast to the Aleo network. You can view this JSON by passing the `--print` flag to `leo execute`. + + + diff --git a/documentation/cli/03_signing.md b/documentation/guides/05_signing.md similarity index 93% rename from documentation/cli/03_signing.md rename to documentation/guides/05_signing.md index 517bc5fea..ce45677e4 100644 --- a/documentation/cli/03_signing.md +++ b/documentation/guides/05_signing.md @@ -1,8 +1,9 @@ --- id: sign -title: Sign and Verify -sidebar_label: Sign and Verify +title: Signing and Verifying +sidebar_label: Signing and Verifying --- +[general tags]: # (guides, sign, verify, signature, private_key, address) In addition to creating accounts, `leo account` can be used to sign data and verify signatures. This can be useful for a particular class of applications that rely on signed data as input. diff --git a/documentation/cli/05_query.md b/documentation/guides/06_query.md similarity index 52% rename from documentation/cli/05_query.md rename to documentation/guides/06_query.md index 57b65a1e3..7ada5d6b3 100644 --- a/documentation/cli/05_query.md +++ b/documentation/guides/06_query.md @@ -1,8 +1,9 @@ --- id: query -title: Retrieving Network Metadata and State +title: Querying Network Metadata and State sidebar_label: Querying the Network --- +[general tags]: # (guides, query) diff --git a/documentation/guides/07_devnet.md b/documentation/guides/07_devnet.md new file mode 100644 index 000000000..8cc597366 --- /dev/null +++ b/documentation/guides/07_devnet.md @@ -0,0 +1,172 @@ +--- +id: devnet +title: Running a Devnet +sidebar_label: Devnet +--- +[general tags]: # (guides, devnet local_devnet, snarkos) + +A local devnet can be a heavyweight but reliable way to test your application on Aleo. + +## Setup + +The Leo CLI provides a helpful command to help startup a local devnet: +```bash +leo devnet --snarkos +``` +The `` is the path to an installed binary of [**snarkOS**](https://github.com/ProvableHQ/snarkOS), the decentralized operating system that forms the backbone of the Aleo network. + +If you don't have snarkOS installed, you can pass the `--install` flag and the CLI will automatically download, compile, and store the binary at the path specified by ``. +```bash +leo devnet --snarkos --install +``` +:::info + +Windows users will need to perform some additional steps in order for snarkOS to install properly: +1. Upon initially installing Rust, you should have been automatically been prompted to install Visual Studio with the MSVC 2022 C++ build tools. +2. Open the Visual Studio Installer and install the C++ Clang Compiler for Windows and either the Windows 10 SDK or Windows 11 SDK (depending on your OS). Make a note of the installation path of the installed tool. It should be of the form `{PATH}\Microsoft Visual Studio\2022\BuildTools`. +3. Within the aforementioned build tools directory, you should find the location of a file called `libclang.dll`. For `x86`-based systems, this should be in the `VC\Tools\Llvm\bin` subdirectory. For `x64`-based systems, this should be in the `VC\Tools\Llvm\x64\bin` subdirectory. +4. Once you have the full path of `libclang.dll`, create the `LIBCLANG_PATH` environment variable for your system and set it to this path. +5. snarkOS should now compile and run properly. + +::: + + + + +The `tmux` command will allow you to toggle between nodes in your local devnet. You can enable this by passing the `--tmux` flag upon startup: +```bash +leo devnet --snarkos --tmux +``` +:::info +This feature is only available on Unix-based systems. +:: + +You'll need to install the `tmux` package first: + + + + +To install `tmux` on macOS, you can use the Homebrew package manager. If you haven't installed Homebrew yet, you can find instructions at their [website](https://brew.sh/). Once Homebrew is installed, run: +```bash +brew install tmux +``` + + +On Ubuntu and other Debian-based systems, you can use the apt package manager: + +```bash +sudo apt update +sudo apt install tmux +``` + + + +Here are some useful (default) commands in `tmux`: +```bash +# To toggle to the next node in a local devnet +Ctrl+b n +# To toggle to the previous node in a local devnet +Ctrl+b p +# To scroll easily, press q to quit +Ctrl+b q +# To select a node in a local devnet +Ctrl+b w +# To select a node manually in a local devnet +Ctrl+b :select-window -t {NODE_ID} +# To stop a local devnet +Ctrl+b :kill-session +``` + +See the full `leo devnet` CLI documentation [here](./../cli/07_devnet.md) + + + +## Usage + +Each time you stop and restart the chain, the prior state and history will be saved. You can clear any prior history by passing the `--clear-storage` flag: +```bash +leo devnet --snarkos --clear-storage +``` +Clearing the ledger history may be useful if you wish to redeploy your program without changing the name. However, this will erase all transaction history and start a new instance of the Aleo blockchain from genesis. + + + +## Deploying and Executing + +When deploying or executing programs on a local devnet, make sure that endpoint is set to `http://localhost:3030` rather than any external API endpoints. You can do this either by manually setting the `ENDPOINT` environment variable, by passing the `--endpoint http://localhost:3030` flag in the CLI, or by setting the `ENDPOINT` variable in a `.env` file within the root directory of your Leo project. + +You will also need credits to fund transactions on the devnet. snarkOS automatically initializes four development accounts funded with Aleo credits that can be used for testing purposes. +```bash +# Account 0 +APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH +AViewKey1mSnpFFC8Mj4fXbK5YiWgZ3mjiV8CxA79bYNa8ymUpTrw +aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px + +# Account 1 +APrivateKey1zkp2RWGDcde3efb89rjhME1VYA8QMxcxep5DShNBR6n8Yjh +AViewKey1pTzjTxeAYuDpACpz2k72xQoVXvfY4bJHrjeAQp6Ywe5g +aleo1s3ws5tra87fjycnjrwsjcrnw2qxr8jfqqdugnf0xzqqw29q9m5pqem2u4t + +# Account 2 +APrivateKey1zkp2GUmKbVsuc1NSj28pa1WTQuZaK5f1DQJAT6vPcHyWokG +AViewKey1u2X98p6HDbsv36ZQRL3RgxgiqYFr4dFzciMiZCB3MY7A +aleo1ashyu96tjwe63u0gtnnv8z5lhapdu4l5pjsl2kha7fv7hvz2eqxs5dz0rg + +# Account 3 +APrivateKey1zkpBjpEgLo4arVUkQmcLdKQMiAKGaHAQVVwmF8HQby8vdYs +AViewKey1iKKSsdnatHcm27goNC7SJxhqQrma1zkq91dfwBdxiADq +aleo12ux3gdauck0v60westgcpqj7v8rrcr3v346e4jtq04q7kkt22czsh808v2 +``` +You can specify the private key to use by manually setting the `PRIVATE_KEY` environment variable, by passing the `--private-key http://localhost:3030` flag in the CLI, or by setting the `PRIVATE_KEY` variable in a `.env` file within the root directory of your Leo project. + +Once your private key and endpoint have been correctly set, deploying and executing largely function the same as they would on Testnet or Mainnet. For more details on either of those processes, check out the [**Deploying**](./03_deploying.md) and [**Executing**](./04_executing.md) guides. + + + +## Querying Transaction Status + +You can check your transactions by using the following API endpoint: + +```bash +GET http://localhost:3030/testnet/transaction/{TRANSACTION_ID} +``` + +or by using `leo query` from the CLI: + +```bash +leo query transaction {TRANSACTION_ID} +``` + +The transaction API endpoint is instructive in verifying whether a transaction succeeded or failed. Since both successful and failed transaction execute a fee transaction, if only the fee transaction appears, that is a clear indication that the transaction has failed. Note that on the Testnet and on Mainnet, failed transactions still require a fee since the network is performing a computation. + +A full list of API endpoints is available [here](https://developer.aleo.org/apis/public_api) + +## Record Scanning + +You can use the CLI from your installed snarkOS binary to view your records. First, navigate to the directory where you installed the binary. The use the following command syntax: +```bash +./snarkos developer scan --endpoint http://localhost:3030 --private-key {YOUR_PRIVATE_KEY} --start --network 1 +``` + +Setting `block_number` to `0` will list all of the records created starting from the genesis block, including your test credit records. + +```bash title="sample output:" +⚠️ Attention - Scanning the entire chain. This may take a while... + +Scanning 3 blocks for records (100% complete)... + +[ + "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 3666670146276262240199958044811329632452609778779651964870759629195088099828group.public}", + "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 4536868268814456227312360347031739423312689137706933033938812386306238998060group.public}", + "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 205967862164714901379497326815256981526025583494109091059194305832749867953group.public}", + "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 4424806931746512507605174575961455750579179367541686805196254590136284583805group.public}" +] +``` + +Setting `block_number` to `1` or higher will exclude the above credit records from the scan. + + diff --git a/documentation/testing/01_test_framework.md b/documentation/guides/08_testing.md similarity index 57% rename from documentation/testing/01_test_framework.md rename to documentation/guides/08_testing.md index 9a05dca4c..7d2da000b 100644 --- a/documentation/testing/01_test_framework.md +++ b/documentation/guides/08_testing.md @@ -1,11 +1,23 @@ --- -id: test_framework -title: Leo's Native Testing Framework +id: test +title: Testing, Testing, 123 sidebar_label: Testing --- +[general tags]: # (guides, tests, testing, unit_testing, integration_testing, devnet, testnet) -## Introduction -The Leo testing frameworks enables developers to validate their Leo program logic by writing unit and integration tests. Tests are written in Leo and are located in a `tests/` subdirectory of the main Leo project directory. +Once deployed, an application lives on the ledger forever. Consequently, it's important to consider every edge case and rigorously test your code. There are number of tools and techniques you can use. + +- [**Unit and Integration Testing**](#test-framework) - Validate Leo program logic through test cases. + +- [**Running a Devnet**](#running-a-devnet) - Deploy and execute on a local devnet. + +- [**Deploying/Executing on Testnet**](#deployingexecuting-on-testnet) - Deploy and execute on the Aleo Testnet. + +- [**Other Tools**](#other-tools) - Tools and methodologies developed by the open-source Aleo community. + + +## Unit and Integration Testing +The Leo testing framework enables developers to validate their Leo program logic by writing unit and integration tests. Tests are written in Leo and are located in a `tests/` subdirectory of the main Leo project directory. ```bash example_program @@ -26,13 +38,11 @@ The test file is a Leo program that imports the program in `main.leo`. The test This tutorial will use an example program which can be found in the [example's repository](https://github.com/ProvableHQ/leo-examples/tree/main/example_with_test). :::info -Developers can add multiple `leo` files to the test directory but must ensure that the name of the test file matches the test program name. For example, if the name of the test file is `test_example_program.leo`, the test program name must be `test_example_program.aleo`. +Developers can add multiple `leo` files to the test directory but must ensure that the name of the test file matches the program name within that test file. For example, if the name of the test file is `test_example_program.leo`, the program name in that file must be `test_example_program.aleo`. ::: -## Testing transition functions. - -### Function logic +### Testing `transition` Functions The `example_program.leo` program contains a transition function which returns the sum of two `u32` inputs. @@ -62,7 +72,7 @@ transition test_simple_addition_fail() { } ``` -## Leo types +### Testing Leo Types Developers can test that record and struct fields match their expected values. In `example_program.leo`, a record is minted transition function shown here: @@ -91,11 +101,11 @@ transition test_record_maker() { ``` :::info -Each test file is required to have at least one transition function. +Each test file is required to have at least one `transition` function. ::: -## Using interpreted tests for modelling on-chain state +### Modeling Onchain State While the testing framework cannot access on-chain state from either `testnet` or `mainnet`, developers can simulate on-chain state in `script`s. A script is interpreted Leo code in which developers are able to await `Future`s and update mappings using interpreted tests. When using interpreted tests, the `transition` or `function` keyword is replaced with the `script` keyword. ```Leo @@ -114,11 +124,11 @@ script test_async() { ``` :::info -External transitions -- async or not -- may be called from test transitions or scripts, but external async functions may only be called directly from scripts. +External `transition`s -- `async` or not -- may be called from test `transition`s or scripts, but external `async function`s may only be called directly from scripts. ::: -## Running tests +### Running Tests Invoking the `leo test` command will run all of the compiled and interpreted tests. Developer may optionally select an individual tests by supplying a a test function name or a string that is contained within a test function name. For instance, to run the test for `test_async`, developers would use the following command: ```bash leo test test_async @@ -132,3 +142,33 @@ or leo test addition ``` +See the `leo test` CLI documentation [here](./../cli/13_test.md) + + +## Running a Devnet + +A local devnet can be a heavyweight but reliable way to test your application on Aleo. + +For more information, refer the to [Devnet](./07_devnet.md) guide + +## Deploying/Executing on Testnet +To deploy and execute on Testnet, you'll need to set your endpoint back to one of the public facing options. Additionally, you'll need to obtain Testnet credits from one of the faucets below: + +### Faucets + + + +At some point you'll need testnet credits. There are a few community-supported faucets to choose from: +- [**Puzzle**](https://dev.puzzle.online/faucet) - 15 credits / 4 hours + +- [**Demox**](https://discord.com/channels/913160862670397510/1202322326230937640/1203135682873266207) - 10 credits / 12 hours + +The faucets are periodically refreshed. + + +## Other Tools + +The Aleo community has developed some neat tools to aid in testing. + +- [**doko.js**](https://github.com/venture23-aleo/doko-js) + diff --git a/documentation/guides/02_debuggin.md b/documentation/guides/09_debugging.md similarity index 88% rename from documentation/guides/02_debuggin.md rename to documentation/guides/09_debugging.md index c40dc3409..1106953ea 100644 --- a/documentation/guides/02_debuggin.md +++ b/documentation/guides/09_debugging.md @@ -1,20 +1,19 @@ --- id: debuggin title: Debuggin' Out -sidebar_label: Debuggin' Out +sidebar_label: Debugging --- +[general tags]: # (guides, debug, debugger, program) `leo debug` is a powerful tool that developers can use to interactively step through executions and track down bugs. In this workshop, we'll use the Leo debugger to explore and gain a deeper understanding of a variety of programs. You will also build up the skills to adeptly use the debugger in your development work. -**This tutorial assumes that you are already familiar with Leo. If you'd like a refresher, see the [Developer Docs](https://docs.leo-lang.org/getting_started/installation)**. - -We're always looking to improve Leo's developer experience. If you have any feedback, please feel free to [file](https://github.com/ProvableHQ/leo/issues/new/choose) an issue! +**This tutorial assumes that you are already familiar with Leo.** # Setup ## Source Material -Install the latest version of the [workshop](https://github.com/ProvableHQ/workshop/). +Download the latest version of the [workshop](https://github.com/ProvableHQ/workshop/tree/master/debuggin-out). ## Leo @@ -181,7 +180,63 @@ Prepared to evaluate: point_math.aleo/sqrt_bitwise(0u32) βœ” Command? Β· #o -Result: 0u32 +Result: 0u32### Cheatsheet + + + +``` +You probably want to start by running a function or transition. +For instance +#into program.aleo/main() +Once a function is running, commands include +#into to evaluate into the next expression or statement; +#step to take one step towards evaluating the current expression or statement; +#over to complete evaluating the current expression or statement; +#run to finish evaluating +#quit to quit the interpreter. + +You can set a breakpoint with +#break program_name line_number + +When executing Aleo VM code, you can print the value of a register like this: +#print 2 + +Some of the commands may be run with one letter abbreviations, such as #i. + +Note that this interpreter is not line oriented as in many common debuggers; +rather it is oriented around expressions and statements. +As you step into code, individual expressions or statements will +be evaluated one by one, including arguments of function calls. + +You may simply enter Leo expressions or statements on the command line +to evaluate. For instance, if you want to see the value of a variable w: +w +If you want to set w to a new value: +w = z + 2u8; + +Note that statements (like the assignment above) must end with a semicolon. + +If there are futures available to be executed, they will be listed by +numerical index, and you may run them using `#future` (or `#f`); for instance +#future 0 + +The interpreter begins in a global context, not in any Leo program. You can set +the current program with + +#set_program program_name + +This allows you to refer to structs and other items in the indicated program. + +The interpreter may enter an invalid state, often due to Leo code entered at the +REPL. In this case, you may use the command + +#restore + +Which will restore to the last saved state of the interpreter. Any time you +enter Leo code at the prompt, interpreter state is saved. + +Input history is available - use the up and down arrow keys. +``` βœ” Command? Β· #i point_math.aleo/sqrt_bitwise(1u32) Prepared to evaluate: diff --git a/documentation/guides/03_program_upgradability.md b/documentation/guides/10_program_upgradability.md similarity index 98% rename from documentation/guides/03_program_upgradability.md rename to documentation/guides/10_program_upgradability.md index 8617b20fb..34e1fab5f 100644 --- a/documentation/guides/03_program_upgradability.md +++ b/documentation/guides/10_program_upgradability.md @@ -3,6 +3,7 @@ id: upgradability title: Upgrading Programs sidebar_label: Upgrading Programs --- +[general tags]: # (guides, upgrade, program, transaction, constructor) # A Developer's Guide to Upgradability in Leo @@ -206,8 +207,7 @@ An upgrade **can**: An upgrade **cannot**: -* Change the input or output signatures of any existing `transition`, `function`, `async function`. -* Change the input signature of any existing `async function` block. +* Change the input or output signatures of any existing `transition`, `function`, `async transition`, or `async function`. * Change the logic within a non-inline `function`. * Modify or delete any existing `struct`, `record`, or `mapping`. * Delete any existing program component. diff --git a/documentation/language/00_overview.md b/documentation/language/00_overview.md index 0a4caab58..a3f2988d6 100644 --- a/documentation/language/00_overview.md +++ b/documentation/language/00_overview.md @@ -3,6 +3,7 @@ id: overview title: The Leo Language Reference sidebar_label: Overview --- +[general tags]: # (syntax) ### Statically Typed diff --git a/documentation/language/01_layout.md b/documentation/language/01_layout.md index 7c5d48930..e75f0b548 100644 --- a/documentation/language/01_layout.md +++ b/documentation/language/01_layout.md @@ -3,8 +3,9 @@ id: layout title: Layout of a Leo Project sidebar_label: Project Layout --- +[general tags]: # (project, project_layout, manifest, module) -### The Manifest +## The Manifest **program.json** is the Leo manifest file that configures our package. ```json title="program.json" @@ -13,7 +14,8 @@ sidebar_label: Project Layout "version": "0.1.0", "description": "", "license": "MIT", - "dependencies": null + "dependencies": null, + "dev_dependencies": null } ``` @@ -22,4 +24,68 @@ The program ID in `program` is the official name that other developers will be a "program": "hello.aleo", ``` -Dependencies will be added to the field of the same name, as they are added. The dependencies are also pegged in the **leo.lock** file. \ No newline at end of file +Dependencies will be added to the field of the same name, as they are added. The dependencies are also pegged in the **leo.lock** file. + +## The Code + +The `src/` directory is where all of your Leo code will live. The main entry point of your project is a file in this directory.appropriately named `main.leo`. Calls to many of the Leo CLI commands will require you to have this file within your project in order to succeed properly. + + +### Modules + +In addition to your main file, Leo also supports a module system as of v3.2.0. + +Leaf modules (i.e. modules without submodules) must be defined in a single file (ex. `foo.leo`). Modules with submodules must be defined by an optional top-level `.leo` file and a subdirectory directory containing the submodules: + + +Take the following project as an example: +``` +src +β”œβ”€β”€ common.leo +β”œβ”€β”€ main.leo +β”œβ”€β”€ outer.leo +└── outer + └── inner.leo +``` + +Given the structure above, the following modules are defined: + +| Filename | Type | Module Name | Access Location & Pattern | +| -------- | ---- | ----------- | ------------------------- | +| `common.leo` | Module | `common` | `main.leo` : `common::` | +| `outer.leo` | Module | `outer` | `main.leo` : `outer::` | +| `outer/inner.leo` | Submodule | `outer::inner` |`main.leo` : `outer::inner::`
`outer.leo` : `inner::`| + +:::info +Only relative paths are implemented so far. That means that items in `outer.leo` cannot be accessed from items in `inner.leo`, for example. This is limiting for now but will no longer be an issue when we add absolute paths. +::: + + +A module file may only contain `struct`, `const`, and `inline` definitions: + +```leo +const X: u32 = 2u32; + +struct S { + a: field +} + +inline increment(x: field) -> field { + return 1field; +} +``` + + + diff --git a/documentation/language/02_structure.md b/documentation/language/02_structure.md index 4a196b161..a92285500 100644 --- a/documentation/language/02_structure.md +++ b/documentation/language/02_structure.md @@ -3,6 +3,7 @@ id: structure title: Structure of a Leo Program sidebar_label: Program Structure --- +[general tags]: # (program, constant, import, transition, async_transition, function, async_function, inline, record, struct, mapping) ## Layout of a Leo Program diff --git a/documentation/language/03_data_types.md b/documentation/language/03_data_types.md index bc28fa157..ebf432ef0 100644 --- a/documentation/language/03_data_types.md +++ b/documentation/language/03_data_types.md @@ -3,6 +3,7 @@ id: data_types title: Data Types sidebar_label: Data Types --- +[general tags]: # (boolean, integer, field, group, scalar, address, signature, array, tuple, struct) ### Booleans diff --git a/documentation/language/04_operators.md b/documentation/language/04_operators.md index b7295724a..6ded566ac 100644 --- a/documentation/language/04_operators.md +++ b/documentation/language/04_operators.md @@ -3,6 +3,7 @@ id: operators title: Operators and Expressions sidebar_label: Operators and Expressions --- +[general tags]: # (operators, cryptographic_operators, assert, hash, commit, random, address, block) ## Operators @@ -1771,9 +1772,9 @@ The instruction will halt if the given `struct` value exceeds the 64-bit limit. ```leo let salt: scalar = ChaCha::rand_scalar(); -let a: address = Pedersen64::commit_to_address(1u8, salt); -let b: field = Pedersen64::commit_to_field(2i64, salt); -let c: group = Pedersen64::commit_to_group(1field, salt); +let a: address = Pedersen128::commit_to_address(1u8, salt); +let b: field = Pedersen128::commit_to_field(2i64, salt); +let c: group = Pedersen128::commit_to_group(1field, salt); ``` #### Description diff --git a/documentation/language/05_control_flow.md b/documentation/language/05_control_flow.md index 1198477ca..32280ef3e 100644 --- a/documentation/language/05_control_flow.md +++ b/documentation/language/05_control_flow.md @@ -3,6 +3,7 @@ id: control title: Control Flow sidebar_label: Control Flow --- +[general tags]: # (loop, conditional, return) ### If Statements diff --git a/documentation/language/06_programs.md b/documentation/language/06_programs.md index 2c153ad83..28a589441 100644 --- a/documentation/language/06_programs.md +++ b/documentation/language/06_programs.md @@ -3,6 +3,7 @@ id: programs title: Programs in Practice sidebar_label: Programs in Practice --- +[general tags]: # (program, mapping, transition, function, inline, async_transition, async_function) ### Mapping Operations diff --git a/documentation/language/07_style.md b/documentation/language/07_style.md index ce02dd9b9..37252fc4f 100644 --- a/documentation/language/07_style.md +++ b/documentation/language/07_style.md @@ -3,6 +3,7 @@ id: style title: Style Guide sidebar: Style Guide --- +[general tags]: # () This guide is provided to point developers in the right direction when writing Leo code. There are many conventions that are unique to the Leo language and the circuits it generates. diff --git a/documentation/language/08_cheatsheet.md b/documentation/language/08_cheatsheet.md index a44abafb6..32b77ef6a 100644 --- a/documentation/language/08_cheatsheet.md +++ b/documentation/language/08_cheatsheet.md @@ -3,6 +3,7 @@ id: cheatsheet title: Leo Syntax Cheatsheet sidebar: Cheatsheet --- +[general tags]: # (program, import, boolean, integer, field, group, scalar, address, signature, array, tuple, struct, operators, cryptographic_operators, assert, hash, commit, random, address, block, transition, async_transition, function, async_function, inline, mapping, conditionals, loops) ## 1. File Import ```leo diff --git a/documentation/leo_by_example/01_auction.md b/documentation/leo_by_example/01_auction.md index 90294dcf4..398bca6f5 100644 --- a/documentation/leo_by_example/01_auction.md +++ b/documentation/leo_by_example/01_auction.md @@ -2,6 +2,7 @@ id: auction title: A Private Auction using Leo --- +[general tags]: # (example, auction, record, program, transition, assert) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/auction)** diff --git a/documentation/leo_by_example/02_basic_bank.md b/documentation/leo_by_example/02_basic_bank.md index 8fb9043e5..e7aa41334 100644 --- a/documentation/leo_by_example/02_basic_bank.md +++ b/documentation/leo_by_example/02_basic_bank.md @@ -2,6 +2,7 @@ id: basic_bank title: A Basic Bank using Leo --- +[general tags]: # (example, bank, record, program, transition, assert, hash, loops, mappings, async_transition, async_function) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/basic_bank)** diff --git a/documentation/leo_by_example/03_vote.md b/documentation/leo_by_example/03_vote.md index a7ced3396..7e3943ba6 100644 --- a/documentation/leo_by_example/03_vote.md +++ b/documentation/leo_by_example/03_vote.md @@ -2,6 +2,7 @@ id: vote title: A Voting Program using Leo --- +[general tags]: # (example, vote, record, program, mapping) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/vote)** diff --git a/documentation/leo_by_example/04_token.md b/documentation/leo_by_example/04_token.md index 10bc92e59..e108926ac 100644 --- a/documentation/leo_by_example/04_token.md +++ b/documentation/leo_by_example/04_token.md @@ -2,6 +2,7 @@ id: token title: A Custom Token in Leo --- +[general tags]: # (example, token, record, program, transition, future, async_transition, async_function) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/token)** diff --git a/documentation/leo_by_example/05_tictactoe.md b/documentation/leo_by_example/05_tictactoe.md index cf3deb479..cbc3e56c2 100644 --- a/documentation/leo_by_example/05_tictactoe.md +++ b/documentation/leo_by_example/05_tictactoe.md @@ -2,6 +2,7 @@ id: tictactoe title: A Game of Tic-Tac-Toe in Leo --- +[general tags]: # (example, tictactoe, program, struct, conditional) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/tictactoe)** diff --git a/documentation/leo_by_example/06_battleship.md b/documentation/leo_by_example/06_battleship.md index a04c6e280..8bbe484b6 100644 --- a/documentation/leo_by_example/06_battleship.md +++ b/documentation/leo_by_example/06_battleship.md @@ -2,6 +2,7 @@ id: battleship title: A Game of Battleship in Leo --- +[general tags]: # (example, battleship, struct, program, transition) **[Source Code](https://github.com/ProvableHQ/leo-examples/tree/main/battleship)** diff --git a/documentation/recipes/00_overview.md b/documentation/recipes/00_overview.md deleted file mode 100644 index 89582f65e..000000000 --- a/documentation/recipes/00_overview.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: overview -title: Overview -sidebar_label: Overview ---- - -Here are a few helpful programming patterns: - -- [**Reading On-Chain State**](./01_using_onchain.md) - Coming soon! - -- [**Upgrading Programs**](./02_upgrading_programs.md) - Coming soon! - diff --git a/documentation/recipes/01_using_onchain.md b/documentation/recipes/01_using_onchain.md deleted file mode 100644 index 11f4ae39d..000000000 --- a/documentation/recipes/01_using_onchain.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: reading_on_chain -title: Reading On-Chain Data -sidebar_label: Reading On-Chain Data ---- - - - -Coming soon! \ No newline at end of file diff --git a/documentation/recipes/02_upgrading_programs.md b/documentation/recipes/02_upgrading_programs.md deleted file mode 100644 index e415f35f7..000000000 --- a/documentation/recipes/02_upgrading_programs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: upgrading_programs -title: Upgrading Programs -sidebar_label: Upgrading Programs ---- - - -Coming soon! \ No newline at end of file diff --git a/documentation/resources/01_curated.md b/documentation/resources/01_curated.md index 60bb72325..d39fb5270 100644 --- a/documentation/resources/01_curated.md +++ b/documentation/resources/01_curated.md @@ -3,6 +3,7 @@ id: curated title: Curated Resources sidebar_label: Curated --- +[general tags]: # (resources, links) There's a lot more on Leo and Aleo out there! Here are some thing you might find interesting. diff --git a/documentation/resources/02_projects.md b/documentation/resources/02_projects.md index 58ca83318..8c2c0687e 100644 --- a/documentation/resources/02_projects.md +++ b/documentation/resources/02_projects.md @@ -3,6 +3,7 @@ id: projects title: Built on Leo sidebar_label: Built on Leo --- +[general tags]: # (projects) diff --git a/documentation/sdk/create-leo-app/00_app_installation.md b/documentation/sdk/create-leo-app/00_app_installation.md deleted file mode 100644 index 65901766f..000000000 --- a/documentation/sdk/create-leo-app/00_app_installation.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: installation -title: Create Leo App -sidebar_label: Installation ---- - - Create Leo App - -## Scaffolding Your First Aleo Project - -:::note -**Compatibility:** -[Node.js](https://nodejs.org/en/) version 18+ -::: - -With NPM: - -```bash -npm create leo-app@latest -``` - -1. Enter the project name. -2. This will prompt you to choose a preferred framework from the following options: - - `React` - - `Node.js` - - `Vanilla (JavaScript)` - -3. If you choose `React` as your framework, the supported templates are: - - `JavaScript` + `Leo` - - `TypeScript` + `React` - - `TypeScript` + `Next.js` - -## More Information - -Based on create-vite: https://github.com/vitejs/vite/tree/main/packages/create-vite diff --git a/documentation/sdk/create-leo-app/01_create_leo_app.md b/documentation/sdk/create-leo-app/01_create_leo_app.md deleted file mode 100644 index 32baf6498..000000000 --- a/documentation/sdk/create-leo-app/01_create_leo_app.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -id: tutorial -title: Create Leo App - React + JS + Leo Tutorial -sidebar_label: React + JS + Leo Tutorial ---- - - Create Leo App - - -## 1. Installation - -Please see [the installation page](00_app_installation.md) to setup the React + Javascript + Leo template. - -## 2. Navigation - -Navigate to the project you just installed. - -```bash -cd aleo-project -npm install -npm run install-leo -npm run dev -``` - - -This installs all the required modules and also Leo, our statically-typed programming language built for writing private applications. Lastly, we've initialized a local instance of your React application at http://localhost:5173. - -`src/App.jsx` contains the main body of your React application. - -The `helloworld` folder is your Leo program. This is where you’ll use Leo. - -`src/workers/worker.js` is the WebAssembly (WASM) module that we'll be initializing for deployment and execution of Leo programs. - -## 3. Execute `helloworld.aleo` - -Navigate to http://localhost:5173 and open up the developer console in your browser - - - -Hit β€œexecute helloworld.aleo”. - -Execution should happen locally and you should see an output pop up. - -![execution-console](./images/execution-console.png) - -![execution-success](./images/execution-success.png) - -## 4. Deploying your Program - -Let’s deploy the `helloworld` program. Deployment requires an account with Aleo credits. - -### Account Generation - -```bash -leo account new -``` - -Write down your private key, view key, and public address in a safe place. Treat your private and view keys as keys you should never share with anyone else. - -### Faucet - -Once you have your account, use our faucet to get some Aleo credits! We have a faucet by text and one via Discord. - -Head to our [faucet page](https://faucet.aleo.org/) and follow the instructions there. - - -After the credits have been disbursed to your address, note your transaction ID down. - -You can also join our [Discord server](https://discord.gg/aleo) and use the `#faucet` channel if texting isn't working. You can send only one request every 20 minutes and can only request 50 credits per hour. Once you send a faucet request, Discord will start a thread under the faucet channel with your request. - -Format: - -```bash -/sendcredits aleo1address amt -``` - -Example: -```bash -/sendcredits aleo1k53lck74r93q70ftjvpkmnl5h9uwcna5wqyt80ggmz5w7lck8syskpxj46 20 -``` - -Note down your transaction ID in the back of the URL from the faucet. The success message in the Discord thread should look like this: - -```bash -have fun https://explorer.provable.com/transaction/... -``` - -### Leo & `helloworld` - -If we try to deploy right now, deployment will fail because `helloworld` has already been deployed before. It's as simple as changing the program name, but let's use Leo to create and build an entirely new program. - -```bash -leo new helloworld_[randomsuffix] -cd helloworld_[randomsuffix] -``` - -After you've generated your new `helloworld` project, you can delete the original `helloworld` folder. - -You'll notice the React App now errors out. Navigate to the home directory of your React application and open `App.jsx`. Change the folder name on line 5 from `helloworld` to the name of your new Leo project to get rid of the error: - -```bash -import helloworld_program from "../helloworld_[randomsuffix]/build/main.aleo?raw"; -``` - -Let's dig in a little more. Navigate back to your Leo project and Add your private key to the `.env` in your new Aleo project. Replace the example private key with the one you saved above. - -```bash -NETWORK=testnet -PRIVATE_KEY=APrivateKey1zkp2FCZZ7ucNVx5hoofizpq18mvCZNKTpqKMTt1wTahmxSf -``` - -Once you've done this, within the root of your new Leo project, you can locally execute your Leo program while developing it: - -```bash -leo run ## compiles leo to aleo instructions and executes program functions with input variables - -leo execute ## compiles leo to aleo instructions, executes a program with input variables, synthesizes the program circuit, and generates proving and verifying keys - -leo help ## you know what this does -``` - -You can try it yourself and observe the outputs in the terminal. - -```bash -leo run main 1u32 2u32 -leo execute main 1u32 2u32 -``` - -Let's get back to deploying! - -When you deploy a program, the record that you requested from the faucet is the one that will be used in order to pay for deployment. Looking in `App.jsx`, the web worker is called in order to start the deployment. Following that to `src/workers/worker.js` we see that the WASM is initalized, which allows for computation to run efficiently in the browser, and that the program manager contains methods for authoring, deploying, and interacting with Aleo programs. - -Thing is, we can hit deploy right now, but it’ll take some time to scan for transactions on the blockchain, so let’s provide the *exact* record that we’ll be pulling the fee from. This significantly quickens the deployment process, and you’ll learn about decrypting records in the process. - -### Decrypting Records - -When you requested credits from the faucet, you are now an owner of a private by default record with credits. Let’s find that record within the transaction. - -Take your transaction ID from the Discord URL earlier: - -```bash -at12u62xwfew2rq32xee8nwhtlxghfjz7mm3528yj240nuezue625fqy4lhlp -``` - -Go to β€œGet Transaction” at [provable.tools/rest](https://provable.tools/rest) and insert your transaction ID to look at the JSON object. You can similarly use https://api.explorer.provable.com/v1/testnet/transaction/[insert-your-transaction-id] to get the same output in your browser. - - -![get-transaction](./images/get-transaction.png) - -Look atΒ `object.execution.transitions[0].outputs[0].value`Β and copy the ciphertext stored there. It should look something like this: - -```bash -record1qyqspk3emhy5wzu4zg59ynhwtcpwg6ez6k4cl9d690hhqcd36pqh3vcpqyxx66trwfhkxun9v35hguerqqpqzqrtc3d8s5qrlufglkk3gkvgj3w2xdul2kl0pxhvt7f85qfxm0dcpt4g5gf6u356sgte9cyzqhj940l6qsdk5uf7u2xcwfv4zrvmeqdpzjrt848 -``` - -Navigate to [provable.tools/record](https://provable.tools/record) and insert the record value along with your view key that you saved earlier. You are the owner of the record, and therefore, you have the view key in order to decrypt it to show the plaintext. - -![decrypt-record](./images/decrypt-record.png) - -Once decrypted, copy the plaintext record and paste it into line 67 of `src/workers/worker.js`. We can comment out line 64 since we don’t want the scanning function active, and instead, we want the optional manual option. - -The final result in `worker.js` should look something like this: - -```javascript -// // Deploy the program to the Aleo network -// const tx_id = await programManager.deploy(program, fee); - -// Optional: Pass in fee record manually to avoid long scan times -const feeRecord = "{owner: aleo1qpjvun06n87jne3jwkml4jwdjqalw7n2qms03mcamenzczrj0uysp85fit.private, microcredits: 50000000u64.private, _nonce: 7736650979063383113375091219637426887776503149825722849440478642541635263210group.public}"; -const tx_id = await programManager.deploy(program, fee, undefined, feeRecord); -``` - -Now you can hit the deploy button! - -![deployment-console](./images/deployment-console.png) - -![deployment-success](./images/deployment-success.png) - -Success, you’ve deployed an Aleo program and can how create a decentralized, private application! - -### 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 -``` - -## Recap & Additional Resources - -1. We packaged a React template for you with Leo. - -2. You also installed [Leo](https://docs.leo-lang.org/leo/), our statically-typed programming language built for writing private applications. Using Leo, you can write, build, compile, and execute Leo programs locally. - -3. We provided the `helloworld` Leo program already pre-compiled into Aleo instructions and then executed it locally using WASM + web workers, which was an abstraction on snarkVM’s capabilities. [snarkVM](https://github.com/ProvableHQ/snarkVM) is the data execution layer. It is used to compile Leo programs and execute them locally off-chain. All Leo programs eventually become Aleo instructions via Aleo’s compiler during the execution phase of snarkVM. - -4. Similarly, we deployed the `helloworld` program, again using the WASM + web workers abstraction layer but you can also deploy programs on-chain using [snarkOS](https://docs.leo-lang.org/testnet/getting_started/deploy_execute/#deploy), the data availability layer or blockchain / distributed ledger. - -5. During the tutorial you navigated to [provable.tools](https://provable.tools), which is the graphical interface to our SDK, which serves as an abstraction layer of snarkOS and snarkVM. You’ll find you can perform similar actions (compiling, executing, deploying) on provable.tools. - - -6. The entire React template along with the WASM and web workers can also be considered an abstraction layer of snarkOS and snarkVM. diff --git a/documentation/sdk/create-leo-app/images/decrypt-record.png b/documentation/sdk/create-leo-app/images/decrypt-record.png deleted file mode 100644 index 50002da47..000000000 Binary files a/documentation/sdk/create-leo-app/images/decrypt-record.png and /dev/null differ diff --git a/documentation/sdk/create-leo-app/images/deployment-console.png b/documentation/sdk/create-leo-app/images/deployment-console.png deleted file mode 100644 index 993c911b2..000000000 Binary files a/documentation/sdk/create-leo-app/images/deployment-console.png and /dev/null differ diff --git a/documentation/sdk/create-leo-app/images/deployment-success.png b/documentation/sdk/create-leo-app/images/deployment-success.png deleted file mode 100644 index 19fb05e0d..000000000 Binary files a/documentation/sdk/create-leo-app/images/deployment-success.png and /dev/null differ diff --git a/documentation/sdk/create-leo-app/images/execution-console.png b/documentation/sdk/create-leo-app/images/execution-console.png deleted file mode 100644 index c75494356..000000000 Binary files a/documentation/sdk/create-leo-app/images/execution-console.png and /dev/null differ diff --git a/documentation/sdk/create-leo-app/images/execution-success.png b/documentation/sdk/create-leo-app/images/execution-success.png deleted file mode 100644 index f20cb0631..000000000 Binary files a/documentation/sdk/create-leo-app/images/execution-success.png and /dev/null differ diff --git a/documentation/sdk/create-leo-app/images/get-transaction.png b/documentation/sdk/create-leo-app/images/get-transaction.png deleted file mode 100644 index 0a4448267..000000000 Binary files a/documentation/sdk/create-leo-app/images/get-transaction.png and /dev/null differ diff --git a/documentation/testing/00_overview.md b/documentation/testing/00_overview.md deleted file mode 100644 index 048c03926..000000000 --- a/documentation/testing/00_overview.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: overview -title: Overview -sidebar_label: Overview ---- - -Once deployed, an application lives on the ledger forever. Consequently, it's important to consider every edge case and rigorously test your code. There are number of tools and techniques you can use. -- [**Unit and Integration Testing**](01_test_framework.md) - Coming soon! - -- [**Debugging**](./02_debugger.md) - Tools and tips to trace errors. - -- [**Running Devnets**](./03_devnet.md) - Deploy and execute on a local devnet. - -- [**Other Tools**](./04_other.md) - Tools and methodologies developer by the open-source Aleo community. - - -## Faucets - -At some point you'll need testnet credits. There are a few community-supported faucets to choose from: -- [**Puzzle**](https://dev.puzzle.online/faucet) - 15 credits / 4 hours - -- [**Demox**](https://discord.com/channels/913160862670397510/1202322326230937640/1203135682873266207) - 10 credits / 12 hours - -The faucets are periodically refreshed. diff --git a/documentation/testing/03_devnet.md b/documentation/testing/03_devnet.md deleted file mode 100644 index deb2be8d5..000000000 --- a/documentation/testing/03_devnet.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: devnet -title: Running a Local Devnet -sidebar_label: Devnet ---- - -A local devnet can be a heavyweight but reliable way to test your application on Aleo. - -## Setup - -To run a local devnet using snarkOS, you'll need to install the latest [snarkOS release](https://github.com/ProvableHQ/snarkOS/releases). -You'll also need `tmux` (instructions below) and the [devnet.sh](https://github.com/ProvableHQ/snarkOS/blob/staging/devnet.sh) script from the [snarkOS repository](https://github.com/ProvableHQ/snarkOS). - -
macOS - -To install `tmux` on macOS, you can use the `Homebrew` package manager. -If you haven't installed `Homebrew` yet, you can find instructions at [their website](https://brew.sh/). -```bash -# Once Homebrew is installed, run: -brew install tmux -``` - -
- -
Ubuntu - -On Ubuntu and other Debian-based systems, you can use the `apt` package manager: -```bash -sudo apt update -sudo apt install tmux -``` - -
- -
Windows - -There are a couple of ways to use `tmux` on Windows: - -## Using Windows Subsystem for Linux (WSL) - -1. First, install [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install). -2. Once WSL is set up and you have a Linux distribution installed (e.g., Ubuntu), open your WSL terminal and install `tmux` as you would on a native Linux system: -```bash -sudo apt update -sudo apt install tmux -``` - -
- -### Runing the Devnet - -From the root of the SnarkOS repository, run the `devnet.sh` script and follow the prompts. Alternatively, you can copy the script to your project's directory. - -```bash -Enter the total number of validators (default: 4): -Enter the total number of clients (default: 2): -Enter the network ID (mainnet = 0, testnet = 1, canary = 2) (default: 1): -Do you want to run 'cargo install --locked --path .' to build the binary? (y/n, default: y): n -Do you want to clear the existing ledger history? (y/n, default: n): -``` -Note: The minimum number of validators to run a local devnet is 4. - -If you have already installed the SnarkOS CLI, you do not need to build the binary. - -Clearing the ledger history may be useful if you wish to redploy your program without changing the name. However, this will erase all transaction history and start a new instance of the Aleo blockchain from genesis. - -`tmux` allows you to toggle between nodes in your local devnet. Here are some useful (default) commands: - -```bash -# To toggle to the next node in a local devnet -Ctrl+b n -# To toggle to the previous node in a local devnet -Ctrl+b p -# To scroll easily, press q to quit -Ctrl+b [ -# To select a node in a local devnet -Ctrl+b w -# To select a node manually in a local devnet -Ctrl+b :select-window -t {NODE_ID} -# To stop a local devnet -Ctrl+b :kill-session -``` - -### Interacting with your program - -## Deploy - -When deploying programs to a local devnet, make sure that your `.env` file matches the one below: - -```bash -NETWORK=testnet -PRIVATE_KEY=APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH -ENDPOINT=http://localhost:3030 -``` - -The PRIVATE_KEY above is same one that is generated by default when you create a new Leo project using the `leo new` command. It will be seeded with ample test credits in the devnet. -To deploy your program, run the following command: -```bash -leo deploy -``` - -## Executing Transactions - -After deploying your program, you can call methods using the following command syntax: -```bash -leo execute [input_1] [input_2] ... [input_n] --program .aleo --broadcast -``` - -## API endpoints - -You can check your transactions by using the following API endpoint: - -```bash -GET http://localhost:3030/testnet/transaction/{transaction_id} -``` - -The transaction API endpoint is instructive in verifying whether a transaction succeeded or failed. Since both successful and failed transaction execute a fee transaction, if only the fee transaction appears, that is a clear indication that the transaction has failed. Note that on the Testnet and on Mainnet, failed transactions still require a fee since the network is performing a computation. - -A full list of API endpoints is available [here](https://developer.aleo.org/references/apis/public_api/) - -## Record Scanning - -You can use the SnarkOS CLI to view your Records using the following command syntax: -```bash -snarkos developer scan --endpoint http://localhost:3030 --private-key APrivateKey1zkp8CZNn3yeCseEtxuVPbDCwSyhGW6yZKUYKfgXmcpoGPWH --start --network 1 -``` - -Setting `block_number` to `0` will list all of the records created starting from the genesis block, including your test credit records. - -```bash -⚠️ Attention - Scanning the entire chain. This may take a while... - -Scanning 3 blocks for records (100% complete)... - -[ - "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 3666670146276262240199958044811329632452609778779651964870759629195088099828group.public}", - "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 4536868268814456227312360347031739423312689137706933033938812386306238998060group.public}", - "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 205967862164714901379497326815256981526025583494109091059194305832749867953group.public}", - "{ owner: aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px.private, microcredits: 23437500000000u64.private, _nonce: 4424806931746512507605174575961455750579179367541686805196254590136284583805group.public}" -] -``` - -Setting `block_number` to `1` or higher will exclude the above credit records from the scan. - - diff --git a/documentation/testing/04_other.md b/documentation/testing/04_other.md deleted file mode 100644 index 7da0145f2..000000000 --- a/documentation/testing/04_other.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: other -title: Other Tools -sidebar_label: Other Tools ---- - -The Aleo community has developed some neat tools to aid in testing. - -- [**Amareleo**](https://amareleo.com/) - -- [**doko.js**](https://github.com/venture23-aleo/doko-js) -