You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In your `main.leo` file, specify any imported dependencies using the `import` keyword before the program declaration:
10
-
```leo
11
-
import credits.aleo;
8
+
Leo programs can import functionality from other programs. Any imported programs are referred to as dependencies. There are two types of dependencies:
12
9
13
-
program test.aleo {
14
-
...
15
-
}
16
-
```
10
+
-**Network dependencies**: Programs already deployed on the Aleo network, fetched as pre-compiled bytecode.
11
+
-**Local dependencies**: Code on your filesystem; either Leo code compiled from source, or Aleo Instructions code.
17
12
18
-
From the root of your Leo program directory, use the `leo add` command to update the `program.json` manifest to add dependencies.
13
+
## Adding Dependencies
19
14
20
-
## Deployed Programs
21
-
When adding a deployed program as a dependency to your program, such as the `credits.aleo`, use the following command::
15
+
### Network Dependencies
22
16
23
-
```
24
-
leo add credits.aleo
17
+
To add a program already deployed on the Aleo network as a dependency:
18
+
```bash
19
+
leo add credits.aleo --network
25
20
```
26
21
or
27
-
```
28
-
leo add credits
22
+
```bash
23
+
leo add credits --network
29
24
```
30
25
31
-
If you are deploying to mainnet, you will need to specify mainnet imports using the `--network` flag as follows:
32
-
33
-
```
26
+
For mainnet dependencies:
27
+
```bash
34
28
leo add credits --network mainnet
35
29
```
36
30
37
-
For the first imported dependency, a new `dependencies` field will be added to the 'package.json` manifest:
38
-
31
+
This adds an entry to your `program.json`:
39
32
```json
40
33
{
41
34
"program": "your_program.aleo",
@@ -53,38 +46,121 @@ For the first imported dependency, a new `dependencies` field will be added to t
53
46
}
54
47
```
55
48
56
-
Dependencies can be removed using the `leo remove` command:
49
+
### Local Dependencies
50
+
51
+
To add a Leo package or Aleo Instructions file from your local filesystem as a dependency:
57
52
```bash
58
-
leo remove credits.aleo
53
+
leo add my_library.aleo --local <PATH_TO_LIBRARY>
59
54
```
60
55
61
-
## Local Development
62
-
When deploying to a local devnet, specify the path for the local dependency as follows:
63
-
64
-
```
65
-
leo add program_name.aleo --local ./path_to_dependency
66
-
```
67
-
The dependencies section in the `program.json` manifest should include the path:
56
+
This records the path in `program.json`:
68
57
```json
69
58
{
70
-
"program": "your_program.aleo",
71
-
"version": "0.0.0",
72
-
"description": "",
73
-
"license": "MIT",
74
59
"dependencies": [
75
60
{
76
-
"name": "local_dependency.aleo",
61
+
"name": "my_library.aleo",
77
62
"location": "local",
78
63
"network": null,
79
-
"path": "./path"
64
+
"path": "./path/to/my_library"
80
65
}
81
66
]
82
-
}
67
+
}
68
+
```
69
+
70
+
Local dependencies are compiled from source whenever you build. They never require network access.
71
+
72
+
## Removing Dependencies
73
+
```bash
74
+
leo remove credits.aleo
75
+
```
76
+
77
+
## Using Dependencies
78
+
79
+
In your `main.leo` file, import dependencies before the program declaration:
80
+
```leo
81
+
import credits.aleo;
82
+
import my_library.aleo;
83
+
84
+
program my_program.aleo {
85
+
// ...
86
+
}
87
+
```
88
+
89
+
## Dependency Resolution Process
90
+
91
+
When you run a Leo command, dependencies are resolved as follows:
92
+
93
+
1.**Read `program.json`** to find declared dependencies
94
+
2.**For each dependency:**
95
+
-**Local**: Read the Leo source from the specified path and compile it, or use Aleo Instructions file
96
+
-**Network**: Fetch the bytecode from the Aleo network (or cache)
97
+
3.**Resolve transitive dependencies** - if your dependency imports other programs, those are fetched too
98
+
4.**Topologically sort** all programs so dependencies are processed before dependents
99
+
100
+
### Caching Behavior
101
+
102
+
Network dependencies are cached locally at `~/.aleo/registry/{network}/{program_name}/{edition}/` to avoid repeated downloads.
103
+
104
+
Different commands handle caching differently:
105
+
106
+
| Command | Cache Behavior |
107
+
|---------|---------------|
108
+
|`leo build`| Uses cache |
109
+
|`leo run`| Uses cache |
110
+
|`leo execute`| Always fetches fresh |
111
+
|`leo deploy`| Always fetches fresh |
112
+
|`leo upgrade`| Always fetches fresh |
113
+
|`leo synthesize`| Always fetches fresh |
114
+
115
+
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.
116
+
117
+
To force a fresh fetch during `build` or `run`:
118
+
```bash
119
+
leo build --no-cache
83
120
```
84
121
85
-
## Recursive Deployment
86
-
When deploying a program that uses local dependencies, use the following command:
122
+
## Program Editions
123
+
124
+
An **edition** is the version number of a deployed program on the Aleo network:
125
+
-**Edition 0:** Initial deployment
126
+
-**Edition 1:** First upgrade
127
+
-**Edition 2:** Second upgrade
128
+
- ...and so on
129
+
130
+
By default, Leo fetches the **latest** edition of a network dependency. To pin to a specific edition:
131
+
```bash
132
+
leo add some_program.aleo --edition 3
133
+
```
134
+
135
+
This records the pinned edition in the manifest:
136
+
```json
137
+
{
138
+
"name": "some_program.aleo",
139
+
"location": "network",
140
+
"network": "testnet",
141
+
"path": null,
142
+
"edition": 3
143
+
}
144
+
```
145
+
146
+
**When to pin editions:**
147
+
- When you need reproducible builds
148
+
- When a dependency upgrade would break your program
149
+
- When you want to avoid unexpected behavior changes
150
+
151
+
**Note:** Local dependencies don't have editions - they're always compiled from your current source code.
152
+
153
+
## Deploying Programs with Dependencies
154
+
155
+
### Recursive Deployment
156
+
157
+
When deploying a program that has local dependencies, use:
87
158
```bash
88
159
leo deploy --recursive
89
160
```
90
-
All local dependency will be deployed in order, followed by the main program. Deployed dependencies will be skipped.
161
+
162
+
This deploys all local dependencies in topological order, then deploys your main program. Dependencies already deployed on-chain are skipped.
163
+
164
+
### Network Dependencies at Deploy Time
165
+
166
+
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.
0 commit comments