diff --git a/docs/rfc/003-imports-stabilization.md b/docs/rfc/003-imports-stabilization.md index cf3ce7c006..5fe231a643 100644 --- a/docs/rfc/003-imports-stabilization.md +++ b/docs/rfc/003-imports-stabilization.md @@ -18,30 +18,62 @@ DRAFT # Summary This proposal aims to improve the import management system in Leo programs to -make program environment more reproducible and predictable. To achieve that -we suggest few changes to Leo CLI and Manifest: +make program environment more reproducible, predictable and compatible. To achieve +that we suggest few changes to Leo CLI and Manifest: - add a "dependencies" section to Leo Manifest and add a command to pull those dependencies; - allow custom names for imports to manually resolve name conflicts; -- store imports as they are called in Leo Manifest; +- add "curve" and "proving system" sections to the Manifest; +- add "include" and "exclude" parameters for "proving system" and "curve"; Later this solution can be improved by adding a lock-file which would lock imported packages based on both their contents and version. # Motivation -What problems does it solve? What is the background? +The current design of imports does not provide any guarantees on what's stored +in program imports and published with the program to Aleo Package Manager. +When a dependency is "added," it is stored inside imports folder, and it is possible +to manually edit and/or add packages in this folder. -Current state: -- imports are published with a program to Aleo PM; -- we treat programs as files with no verification of imports (they can be changed locally and published in that state); -- name collisions cannot be resolved; a new import overwrites existing; +Also, imports are stored under the package name which makes it impossible to import +two different packages with the same name. -TBD +Another important detail in the scope of this proposal is that in future Leo +programs will have the ability to be run with different proving systems +and curves, possibly creating incompatibility between programs written +for different proving systems or curves. To make a foundation for these features, +imports need to be managed with include/exclude lists for allowed (compatible) +proving systems and curves. # Design -## Leo Manifest +## Leo Manifest - target section + +To lay the foundation for the future of the Leo ecosystem and start integrating +information about programs compatibility we suggest adding two new fields to +the new `[target]` section of the Leo Manifest: `proving_system` and `curve`. + +Currently, the Leo compiler only supports `Groth16` for the proving system and `Bls12_377` +for the curve, they are meant to be default values in Leo Manifest. + +```toml +[project] +name = "first" +version = "0.1.0" +description = "The first package" +license = "MIT" + +[target] +curve = "Bls12_377" +proving_system = "Groth16" +``` + +These fields are meant to be used to determine whether imported program is +compatible to the original when support for different curves and proving systems +is added. + +## Leo Manifest - dependencies Dependencies section: @@ -49,13 +81,27 @@ Dependencies section: [dependencies] name = { author = "author", package = "package", version = "version" } +# alternative way of adding dependency record [dependencies.name] author = "author" package = "package" version = "1.0" ``` -TBD +### Parameters description + +`name` field sets the name of the dependency in Leo code. That way we allow +developer to resolve collisions in import names manually. So, for example, +if a developer is adding `howard/silly-sudoku` package to his program, he +might define its in-code name as `sudoku` and import it with that name: + +```ts +import sudoku; +``` + +`package`, `author` and `version` are package name, package author and +version respectively. They are already used as arguments in `leo add` +command, so these fields are already understood by the Leo developers. ## Leo CLI @@ -63,21 +109,62 @@ To support updated Manifest new command should be added to Leo CLI. ```bash # pull imports -leo pull +leo install +``` + +Alternatively it can be called `pull`. +``` +leo pull ``` ## Imports Restructurization One of the goals of proposed changes is to allow importing packages with the -same name but different authors. To resolve name conflict we suggest storing -imports as they are named in Leo Manifest file (Leo.toml). +same name but different authors. This has to be solved not only on the +language level but also on the level of storing program imports. + +We suggest using set of all 3 possible program identifiers for import +folder name: `author-package@version`. Later it can be extended to +include hash for version, but having the inital set already solves name +collisions. + +So, updated imports would look like: + +``` +leo-program +├── Leo.toml +├── README.md +├── imports +│ ├── author1-program@0.1.0 +│ │ └── ... +│ ├── author2-program2@1.0.4 +│ └── ... +├── inputs +│ └── ... +└── src + └── main.leo +``` + +This change would also affect the way imports are being processed on the ASG +level, and we'd need to add an imports map as an argument to the Leo compiler. +The Leo Manifest's dependencies sections needs to be parsed and passed as +a hashmap to the compiler: + +``` +first-program => author1-program@0.1.0 +second-program => author2-program2@1.0.4 +``` +## Recursive Dependencies - +Later this solution can be improved by building a lock file containing all the +information on program dependencies, and the file itself will have enough data +to track and prevent recursion. # Drawbacks @@ -85,6 +172,8 @@ This change might require the update of already published programs on Aleo PM du Leo Manifest change. However it is possible to implement it in a backward-compatible way. +It also introduces the danger of having recursive dependencies, this problem is addressed in the Design section above. + # Effect on Ecosystem Proposed improvement provides safety inside Leo programs and should not affect