Improve dependency management documentation #556
Conversation
- 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
JoshuaBatty
requested review from
AleoAlexander,
d0cd,
mohammadfawaz and
vicsn
| ```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 | ||
| ``` |
There was a problem hiding this comment.
I think it's best practice to always include the --network flag, even for Testnet.
There was a problem hiding this comment.
My instinct is to only show flags when they're necessary, since testnet is the default, leo add credits just works. Showing --network testnet everywhere might imply it's required when it's not. The mainnet example already demonstrates the flag exists for when you need it. Thoughts?
There was a problem hiding this comment.
Turns out this guide is old. leo add was changed so that one of the following is required:
<--local <LOCAL>|--network|--edition <EDITION>>For some reason, you can't specify the network here. I imagine that it uses either the environment variable, the .env file, or the CLI argument when you call leo build.
| ## 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 | | ||
| | `leo run` | Uses cache | | ||
| | `leo execute` | Always fetches fresh | | ||
| | `leo deploy` | Always fetches fresh | | ||
| | `leo upgrade` | Always fetches fresh | | ||
| | `leo synthesize` | Always fetches fresh | | ||
|
|
||
| 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`: | ||
| ```bash | ||
| leo build --no-cache | ||
| ``` |
There was a problem hiding this comment.
I recommend moving this section to the bottom of the page
There was a problem hiding this comment.
I'd lean towards keeping it here. The flow goes from "how resolution works" → "caching" → "editions" → "deployment", which follows the conceptual order a reader would encounter these ideas.
Moving editions after deployment feels like an afterthought when it's actually core to understanding what gets fetched. Happy to move it if you feel strongly though!
There was a problem hiding this comment.
I don't have a strong preference, so let's keep it as is!
vicsn
left a comment
vicsn
left a comment
There was a problem hiding this comment.
I have a few questions but overall LGTM.
Would love a redesign to make it simpler to use for developers.
| } | ||
| ``` | ||
|
|
||
| Local dependencies are compiled from source whenever you build. They never require network access. |
There was a problem hiding this comment.
Will dependencies of the local dependency be fetched from the network?
There was a problem hiding this comment.
Yes, transitive dependencies are fetched based on their own location type. If your local dependency imports a network program, that gets fetched from the network. If it imports another local path, that's read from disk.
| - 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. |
There was a problem hiding this comment.
What happens when the local dependency also lives in the network?
In any case, it must have some edition right, either 0 if this is the first deployment or perhaps higher if it's already present?
Not sure if the edition is actually materially used for anything.
There was a problem hiding this comment.
If it's marked as local, Leo just compiles from source and ignores any network presence. Editions only come into play for network dependencies - they tell Leo which on-chain version to fetch. Local deps don't have editions because you're compiling your source, not fetching bytecode.
At deploy time, if the local dep hasn't been deployed yet it becomes edition 0. If it already exists on-chain, the deploy would fail (you'd need to upgrade instead).
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Co-authored-by: Alexander Kim <[email protected]> Signed-off-by: Joshua Batty <[email protected]>
Agreed. Once we have the lock file actually populated a lot of this complexity around edition pinning goes away. Leo would just auto-record resolved editions on first build, and developers wouldn't need to think about it unless they explicitly want to update. |
Structure Changes
Content Changes
execute,deploy,upgrade,synthesize) bypass cacheRendered
Motivation
This documentation update accompanies ProvableHQ/leo#29027 which improves edition handling for dependencies. The existing docs did not clearly explain the distinction between local and network dependencies, or why different commands handle caching differently. This should help clarify these concepts for users.