From 28054a6e6ebe2d710c3bfb0c82f2dc868f2007b9 Mon Sep 17 00:00:00 2001 From: JoshuaBatty Date: Wed, 10 Dec 2025 12:55:37 +1100 Subject: [PATCH 01/15] Document dependency resolution, caching behavior, and edition pinning --- documentation/guides/02_dependencies.md | 50 ++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 5f2391b75..3ef8af2ec 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -87,4 +87,52 @@ When deploying a program that uses local dependencies, use the following command ```bash leo deploy --recursive ``` -All local dependency will be deployed in order, followed by the main program. Deployed dependencies will be skipped. \ No newline at end of file +All local dependency will be deployed in order, followed by the main program. Deployed dependencies will be skipped. + +## How Dependencies are Resolved + +**Local dependencies** (`location: local`) are compiled from Leo source code in the specified path. They never require network access. + +**Network dependencies** (`location: network`) are fetched as bytecode from the Aleo network. Leo caches these in `~/.aleo/registry/{network}/{program_name}/{edition}/` to avoid repeated downloads. + +### Caching Behavior + +Different commands handle caching differently: + +| Command | Cache Behavior | +|---------|---------------| +| `leo build` | Uses cache (fetches only if not cached) | +| `leo run` | Uses cache | +| `leo execute` | Always fetches fresh from network | +| `leo deploy` | Always fetches fresh from network | +| `leo upgrade` | Always fetches fresh from network | +| `leo synthesize` | Always fetches fresh from network | + +Commands that generate proofs or interact with the blockchain (`execute`, `deploy`, `upgrade`, `synthesize`) always fetch fresh bytecode to ensure consistency with the current network state. + +To force a fresh fetch during `build` or `run`, use the `--no-cache` flag: +```bash +leo build --no-cache +``` + +### Editions + +An **edition** is the version number of a deployed program on the Aleo network. Edition 0 is the initial deployment, and the edition is incremented by 1 each time the program is upgraded. + +By default, Leo fetches the **latest** edition of a network dependency. To pin a dependency to a specific edition: +```bash +leo add some_program.aleo --edition 3 +``` + +This records the pinned edition in the manifest: +```json +{ + "name": "some_program.aleo", + "location": "network", + "network": "testnet", + "path": null, + "edition": 3 +} +``` + +Pinning is useful when you need reproducible builds or want to avoid breaking changes if a dependency is upgraded. \ No newline at end of file From bab328414723c3aea61f1669fc714feb9aae7283 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Thu, 11 Dec 2025 13:09:59 +1100 Subject: [PATCH 02/15] Improve dependency docs with clearer explanations and structure - Restructure to explain local vs network dependencies upfront - Add step-by-step dependency resolution explanation - Explain why proof-generating commands bypass cache - Document edition pinning use cases - Add V8 constructor requirement note for deploy --- documentation/guides/02_dependencies.md | 134 ++++++++++++++---------- 1 file changed, 81 insertions(+), 53 deletions(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 3ef8af2ec..9018c81b9 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -1,41 +1,34 @@ --- -id: dependencies +id: dependencies title: Dependency Management sidebar_label: Dependency Management --- [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; +Leo programs can depend on other Aleo programs. There are two types of dependencies: -program test.aleo { -... -} -``` +- **Network dependencies**: Programs already deployed on the Aleo network, fetched as pre-compiled bytecode. +- **Local dependencies**: Leo source code on your filesystem, compiled from source. -From the root of your Leo program directory, use the `leo add` command to update the `program.json` manifest to add dependencies. +## Adding Dependencies -## Deployed Programs -When adding a deployed program as a dependency to your program, such as the `credits.aleo`, use the following command:: +### Network Dependencies -``` +To depend on a program deployed on the Aleo network: +```bash leo add credits.aleo ``` or -``` +```bash leo add credits ``` -If you are deploying to mainnet, you will need to specify mainnet imports using the `--network` flag as follows: - -``` +For mainnet programs, specify the network: +```bash leo add credits --network mainnet ``` -For the first imported dependency, a new `dependencies` field will be added to the 'package.json` manifest: - +This adds an entry to your `program.json`: ```json { "program": "your_program.aleo", @@ -53,73 +46,88 @@ For the first imported dependency, a new `dependencies` field will be added to t } ``` -Dependencies can be removed using the `leo remove` command: +### Local Dependencies + +To depend on a Leo package on your filesystem: ```bash -leo remove credits.aleo +leo add my_library.aleo --local ./path/to/my_library ``` -## Local Development -When deploying to a local devnet, specify the path for the local dependency as follows: - -``` -leo add program_name.aleo --local ./path_to_dependency -``` -The dependencies section in the `program.json` manifest should include the path: +This records the path in `program.json`: ```json { - "program": "your_program.aleo", - "version": "0.0.0", - "description": "", - "license": "MIT", "dependencies": [ { - "name": "local_dependency.aleo", + "name": "my_library.aleo", "location": "local", "network": null, - "path": "./path" + "path": "./path/to/my_library" } ] -} +} ``` -## Recursive Deployment -When deploying a program that uses local dependencies, use the following command: +Local dependencies are compiled from source whenever you build. They never require network access. + +### Removing Dependencies ```bash -leo deploy --recursive +leo remove credits.aleo ``` -All local dependency will be deployed in order, followed by the main program. Deployed dependencies will be skipped. -## How Dependencies are Resolved +## Using Dependencies in Code -**Local dependencies** (`location: local`) are compiled from Leo source code in the specified path. They never require network access. +In your `main.leo`, import dependencies before the program declaration: +```leo +import credits.aleo; +import my_library.aleo; -**Network dependencies** (`location: network`) are fetched as bytecode from the Aleo network. Leo caches these in `~/.aleo/registry/{network}/{program_name}/{edition}/` to avoid repeated downloads. +program my_program.aleo { + // ... +} +``` + +## How Dependency Resolution Works + +When you run a Leo command, dependencies are resolved as follows: + +1. **Read `program.json`** to find declared dependencies +2. **For each dependency:** + - **Local**: Read the Leo source from the specified path and compile it + - **Network**: Fetch the bytecode from the Aleo network (or cache) +3. **Resolve transitive dependencies** - if your dependency imports other programs, those are fetched too +4. **Topologically sort** all programs so dependencies are processed before dependents ### Caching Behavior +Network dependencies are cached locally at `~/.aleo/registry/{network}/{program_name}/{edition}/` to avoid repeated downloads. + Different commands handle caching differently: | Command | Cache Behavior | |---------|---------------| -| `leo build` | Uses cache (fetches only if not cached) | +| `leo build` | Uses cache | | `leo run` | Uses cache | -| `leo execute` | Always fetches fresh from network | -| `leo deploy` | Always fetches fresh from network | -| `leo upgrade` | Always fetches fresh from network | -| `leo synthesize` | Always fetches fresh from network | +| `leo execute` | Always fetches fresh | +| `leo deploy` | Always fetches fresh | +| `leo upgrade` | Always fetches fresh | +| `leo synthesize` | Always fetches fresh | -Commands that generate proofs or interact with the blockchain (`execute`, `deploy`, `upgrade`, `synthesize`) always fetch fresh bytecode to ensure consistency with the current network state. +Commands that generate proofs (`execute`, `deploy`, `upgrade`, `synthesize`) always fetch fresh bytecode because proofs include commitments to the exact bytecode of dependencies. Using stale cached bytecode would produce invalid proofs if a dependency has been upgraded on-chain. -To force a fresh fetch during `build` or `run`, use the `--no-cache` flag: +To force a fresh fetch during `build` or `run`: ```bash leo build --no-cache ``` -### Editions +## Editions (Program Versions) -An **edition** is the version number of a deployed program on the Aleo network. Edition 0 is the initial deployment, and the edition is incremented by 1 each time the program is upgraded. +An **edition** is the version number of a deployed program on the Aleo network: +- Edition 0: Initial deployment +- Edition 1: First upgrade +- Edition 2: Second upgrade +- ...and so on -By default, Leo fetches the **latest** edition of a network dependency. To pin a dependency to a specific edition: +By default, Leo fetches the **latest** edition of a network dependency. To pin to a specific edition: ```bash leo add some_program.aleo --edition 3 ``` @@ -135,4 +143,24 @@ This records the pinned edition in the manifest: } ``` -Pinning is useful when you need reproducible builds or want to avoid breaking changes if a dependency is upgraded. \ No newline at end of file +**When to pin editions:** +- When you need reproducible builds +- When a dependency upgrade would break your program +- When you want to avoid unexpected behavior changes + +**Note:** Local dependencies don't have editions - they're always compiled from your current source code. + +## Deploying Programs with Dependencies + +### Recursive Deployment + +When deploying a program that has local dependencies, use: +```bash +leo deploy --recursive +``` + +This deploys all local dependencies in topological order, then deploys your main program. Dependencies already deployed on-chain are skipped. + +### Network Dependencies at Deploy Time + +When you deploy, Leo fetches fresh bytecode for all network dependencies to ensure your deployment transaction references the current on-chain editions. If a network dependency is at edition 0 and lacks a constructor (required since the V8 consensus upgrade), Leo will error with a clear message explaining that the dependency needs to be upgraded on-chain first. From 29a6fc4ec0587d841cfafc827c712ef357af86b4 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:08:38 +1100 Subject: [PATCH 03/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 9018c81b9..22b9946ce 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -5,7 +5,7 @@ sidebar_label: Dependency Management --- [general tags]: # (guides, dependency, dependency_management, imports, program) -Leo programs can depend on other Aleo programs. There are two types of dependencies: +Leo programs can import functionality from other programs. Any imported programs are referred to as dependencies. There are two types of dependencies: - **Network dependencies**: Programs already deployed on the Aleo network, fetched as pre-compiled bytecode. - **Local dependencies**: Leo source code on your filesystem, compiled from source. From f1aba38edfd7ca7b571ca44b9e94d94d2d533a46 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:09:38 +1100 Subject: [PATCH 04/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 22b9946ce..8c2191110 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -14,7 +14,7 @@ Leo programs can import functionality from other programs. Any imported program ### Network Dependencies -To depend on a program deployed on the Aleo network: +To add a program already deployed on the Aleo network as a dependency: ```bash leo add credits.aleo ``` From a9df015df3b3e8d1ba2dfdee39ab8f18554b4eb6 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:12:03 +1100 Subject: [PATCH 05/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 8c2191110..aaf7a1182 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -119,7 +119,7 @@ To force a fresh fetch during `build` or `run`: leo build --no-cache ``` -## Editions (Program Versions) +## Program Editions An **edition** is the version number of a deployed program on the Aleo network: - Edition 0: Initial deployment From c3beff09e07ead62acf64a5ce45ca8eaede8f5f8 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:12:33 +1100 Subject: [PATCH 06/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index aaf7a1182..c3df739c8 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -122,9 +122,9 @@ leo build --no-cache ## Program Editions An **edition** is the version number of a deployed program on the Aleo network: -- Edition 0: Initial deployment -- Edition 1: First upgrade -- Edition 2: Second upgrade +- **Edition 0:** Initial deployment +- **Edition 1:** First upgrade +- **Edition 2:** Second upgrade - ...and so on By default, Leo fetches the **latest** edition of a network dependency. To pin to a specific edition: From cbfeb8c2ba80257fd88cfce1ad15c748c05c84c3 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:13:38 +1100 Subject: [PATCH 07/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index c3df739c8..89fb44aec 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -8,7 +8,7 @@ sidebar_label: Dependency Management Leo programs can import functionality from other programs. Any imported programs are referred to as dependencies. There are two types of dependencies: - **Network dependencies**: Programs already deployed on the Aleo network, fetched as pre-compiled bytecode. -- **Local dependencies**: Leo source code on your filesystem, compiled from source. +- **Local dependencies**: Code on your filesystem; either Leo code compiled from source, or Aleo Instructions code. ## Adding Dependencies From 03a8bc7f1930e7376aa5c456092cf832a391eb07 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:14:22 +1100 Subject: [PATCH 08/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 89fb44aec..1f3b8ef61 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -48,7 +48,7 @@ This adds an entry to your `program.json`: ### Local Dependencies -To depend on a Leo package on your filesystem: +To add a Leo package or Aleo Instructions file from your local filesystem as a dependency: ```bash leo add my_library.aleo --local ./path/to/my_library ``` From ee4fcb3fcff95bbe26b3b0c1f3b390487467cd50 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:14:37 +1100 Subject: [PATCH 09/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 1f3b8ef61..591986cde 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -86,7 +86,7 @@ program my_program.aleo { } ``` -## How Dependency Resolution Works +## Dependency Resolution Process When you run a Leo command, dependencies are resolved as follows: From c6d9f97769fd805f761ac9134dafa3421b939e8a Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Fri, 12 Dec 2025 11:14:51 +1100 Subject: [PATCH 10/15] Update documentation/guides/02_dependencies.md Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 591986cde..4c9c2452b 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -92,7 +92,7 @@ When you run a Leo command, dependencies are resolved as follows: 1. **Read `program.json`** to find declared dependencies 2. **For each dependency:** - - **Local**: Read the Leo source from the specified path and compile it + - **Local**: Read the Leo source from the specified path and compile it, or use Aleo Instructions file - **Network**: Fetch the bytecode from the Aleo network (or cache) 3. **Resolve transitive dependencies** - if your dependency imports other programs, those are fetched too 4. **Topologically sort** all programs so dependencies are processed before dependents From f8bab6dfe2dfedab2b1494a5ee08f766bb693c69 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Mon, 5 Jan 2026 10:37:58 +1100 Subject: [PATCH 11/15] feedback --- documentation/guides/02_dependencies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 4c9c2452b..e93237a5e 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -16,14 +16,14 @@ Leo programs can import functionality from other programs. Any imported program To add a program already deployed on the Aleo network as a dependency: ```bash -leo add credits.aleo +leo add credits.aleo --network ``` or ```bash -leo add credits +leo add credits --network ``` -For mainnet programs, specify the network: +For mainnet dependencies: ```bash leo add credits --network mainnet ``` From 289939cb0222f4790ae3a360e5b9447365a20df1 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Tue, 24 Feb 2026 11:03:02 +1100 Subject: [PATCH 12/15] Apply suggestion from @AleoAlexander Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index e93237a5e..1b48de5e3 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -76,7 +76,7 @@ leo remove credits.aleo ## Using Dependencies in Code -In your `main.leo`, import dependencies before the program declaration: +In your `main.leo` file, import dependencies before the program declaration: ```leo import credits.aleo; import my_library.aleo; From f2431ba9321527b8166be2ab5f854bc256954351 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Tue, 24 Feb 2026 11:03:16 +1100 Subject: [PATCH 13/15] Apply suggestion from @AleoAlexander Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 1b48de5e3..4e273640c 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -74,7 +74,7 @@ Local dependencies are compiled from source whenever you build. They never requi leo remove credits.aleo ``` -## Using Dependencies in Code +## Using Dependencies In your `main.leo` file, import dependencies before the program declaration: ```leo From 018bf25ea3a6bd458b2e28d27bc3ccff089783be Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Tue, 24 Feb 2026 11:03:27 +1100 Subject: [PATCH 14/15] Apply suggestion from @AleoAlexander Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index 4e273640c..b6bc6d038 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -69,7 +69,7 @@ This records the path in `program.json`: Local dependencies are compiled from source whenever you build. They never require network access. -### Removing Dependencies +## Removing Dependencies ```bash leo remove credits.aleo ``` From 1d2bc265df82d6e0f935c7c1af33e796168ec867 Mon Sep 17 00:00:00 2001 From: Joshua Batty Date: Tue, 24 Feb 2026 11:03:49 +1100 Subject: [PATCH 15/15] Apply suggestion from @AleoAlexander Co-authored-by: Alexander Kim Signed-off-by: Joshua Batty --- documentation/guides/02_dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guides/02_dependencies.md b/documentation/guides/02_dependencies.md index b6bc6d038..b32527731 100644 --- a/documentation/guides/02_dependencies.md +++ b/documentation/guides/02_dependencies.md @@ -50,7 +50,7 @@ This adds an entry to your `program.json`: To add a Leo package or Aleo Instructions file from your local filesystem as a dependency: ```bash -leo add my_library.aleo --local ./path/to/my_library +leo add my_library.aleo --local ``` This records the path in `program.json`: