From 5d1465ac4e2e804e050971af49d8a357ed961bdb Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Fri, 30 Sep 2022 16:53:50 -0700 Subject: [PATCH 1/5] commit arc 3 specification --- arc-0003/README.md | 314 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 arc-0003/README.md diff --git a/arc-0003/README.md b/arc-0003/README.md new file mode 100644 index 0000000..7552094 --- /dev/null +++ b/arc-0003/README.md @@ -0,0 +1,314 @@ +--- +arc: 3 +title: Testnet 3.2 +authors: @acoglio, @bendyarm, @collinc97, @d0cd, @howardwu +discussion: ARC-0003: Testnet 3.2 +topic: Language +status: Draft +created: 9-29-2022 +--- + +## Abstract + +The purpose of this ARC is to unify syntax between Leo and Aleo instructions to make it clear what tools developers have at their disposal. We propose several breaking changes to both Leo and Aleo instructions to achieve this goal. + +Leo breaking changes: +* Add `program name.network {}` scope +* Add `interface` abstract type +* Change `circuit` type -> `struct` type +* Change `@program function` -> `transition` + + +Aleo instructions breaking changes: +* Add `interface` abstract type +* Change `interface` type -> `struct` type +* Change `function` -> `transition` +* Change `closure` -> `function` + +## Specification + +### Program Scope + +The program scope definition `program name.network {}` is a new Leo feature that expresses Aleo programs inside a Leo file more clearly. + +**Leo code** +```rust= +import bar.leo; + +program foo.aleo { + mapping balances: address => u64; + + record token { + owner: address, + gates: u64, + amount: u64, + } + + struct message { + sender: address, + object: u64, + } + + transition mint(owner: address, amount: u64) -> token { ... } + + function compute(a: u64, b: u64) -> u64 { ... } +} +``` +The following must be defined inside the program scope in a Leo file. +* mapping definitions +* record types +* struct types +* transition function definitions +* helper function definitions + +The following must be defined outside the program scope in a Leo file. +* import definitions +* interface definitions. + +### Interface Abstract Type +Interfaces are being added to both Leo and Aleo instructions to relate types that have similar implementations. +Interfaces are similar to classes in object-oriented programming languages. + +Interfaces can define +* mappings +* transition functions +* helper functions + +Interfaces cannot define +* record types +* struct types + +**Leo code** +```rust= +interface fooable { + mapping balances: address => u64; + + transition compute(amount: u64) -> u64; +} + +program foo.aleo is fooable { + mapping balances: address => u64; + + transition compute(amount: u64) -> u64 { + return amount + 1u64; + } +} +``` + +Interfaces can be implemented by programs with the `is` keyword. +Interfaces must be defined within a [program scope](#program-scope). +Interfaces cannot be instantiated on their own. + + +**Aleo instructions** +```rust= +// @howardwu how do you want to write interfaces? +interface fooable; + +mapping balances: + key left as address.public; + value right as u64.public; + +program foo.aleo is fooable; + +mapping balances: + key left as address.public; + value right as u64.public; +``` + +Interfaces can be implemented by programs with the `is` keyword. +Interfaces cannot be instantiated on their own. + + +### Struct Type + +**Leo code** +```rust= +struct message { + sender: address, + object: u64, +} + +``` +Structs must be defined within a [program scope](#program-scope). +Structs can be instantiated. +Structs can be called by external programs. + +**Aleo instructions** +```rust= +struct message: + sender as address.private; + object as u64.private; +``` +Structs must be defined after the program declaration `program foo.aleo;` +Structs can be instantiated. +Structs can be called by external programs. + + +### Transition Function +A transition function is an external function that can modify or create records. +In Aleo's architecture, transitions are datatypes inside of transactions that detail modification or creation of record objects. + +Transition functions can call helper [functions](#function). +Transition functions can call other transition functions defined in an external program. +Transition functions cannot call other transition functions defined in the same program. + +Although transition functions are introduced with the single keyword `transition`, +documentation should refer to them as "transition functions", not "transitions". + +**Leo code** +```rust= +program foo.aleo { + mapping balances: address => u64; + + record token { + owner: address, + gates: u64, + amount: u64, + } + + transition mint(public sender: address, public amount: u64) -> token { + return token { + owner: sender, + gates: 0u64, + amount, // Shorthand syntax + } then finalize(sender, amount); + } + + finalize mint(sender: address, amount: u64) { + increment(balances, sender, amount); + } +} +``` +In Leo, transition functions were previously written as `@program function` - this syntax is now deprecated. +Transition functions must be defined within a [program scope](#program-scope). +Transition functions can have an associated `finalize` function with the same name that modifies data in a public mapping. + + +**Aleo instructions** +```rust= +program foo.aleo; + +mapping balances: + key left as address.public; + value right as u64.public; + +record token: + owner as address.private; + gates as u64.private; + amount as u64.private; + +transition mint: + input r0 as address.public; + input r1 as u64.public; + cast r0 0u64 r1 into r2 as token.record; + output r2 as token.record; + finalize r0 r1; + +finalize mint: + input r0 as address.public; + input r1 as u64.public; + increment balances[r0] by r1; +``` +In Aleo instructions, transition functions were previously written as `function` - this syntax now defines (helper) [functions](#function). +Transition function can have an associated `finalize` function with the same name that modifies data in a public mapping. + + +### Helper Function +All other functions are helper functions that do not modify or create records. +Functions cannot call other functions. +Functions cannot call transition functions. + +**Leo code** +```rust= +program foo.aleo { + function compute(a: u64, b: u64) -> u64 { + return a + b; + } +} + +``` +Functions must be defined within a [program scope](#program-scope). + + +**Aleo instructions** +```rust= +program foo.aleo; + +function compute: + input r0 as u64.private; + input r1 as u64.private; + add r0 r1 into r2; + output r2 as u64.private; +``` +In Aleo instructions, functions were previously written as `closure` - this syntax is now deprecated. + + +### Test Cases + +Each case outlined in the specification of each feature should be tested. + +## Reference Implementations + +This section should contain links to reference implementations that the community can review to evaluate the +quality, complexity, and completeness of the new ARC standard. + +## Dependencies + +This will affect the SnarkVM, Aleo, and Leo repositories. +All grammar and documentation repositories will also need to be updated. + +### Backwards Compatibility + +(The 'V1' and 'V2' designations refer to Leo and Aleo instructions before and after the change proposed by this ARC. They do not refer to official release versions.) + +| Leo V1 | Leo V2 | +|-------------------|--------------| +| --- | program | +| ∅ | interface | +| mapping | mapping | +| circuit | struct | +| record | record | +| @program function | transition | +| function | function | +| name.network | name.network | + +| Aleo Instructions V1 | Aleo Instructions V2 | +|----------------------|----------------------| +| program | program | +| ∅ | interface | +| mapping | mapping | +| interface | struct | +| record | record | +| function | transition | +| closure | function | +| name.network | name.network | + + +[//]: # (// Todo: Keep the two tables above or the single table below.) +[//]: # () +[//]: # (| Leo V1 | Leo V2 | Aleo V2 | Aleo V1 |) + +[//]: # (|--------------|--------------|--------------|--------------|) + +[//]: # (| ∅ | program | program | program |) + +[//]: # (| ∅ | interface | interface | ∅ |) + +[//]: # (| mapping | mapping | mapping | mapping |) + +[//]: # (| circuit | struct | struct | interface |) + +[//]: # (| record | record | record | record |) + +[//]: # (| @program | transition | transition | function |) + +[//]: # (| function | function | function | closure |) + +[//]: # (| name.network | name.network | name.network | name.network |) + + +## Security & Compliance + + +## References From 438a1a4d56897597c013377ca6ec4ef6e66dfa8e Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Mon, 3 Oct 2022 10:21:31 -0700 Subject: [PATCH 2/5] update ARC name --- arc-0003/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/arc-0003/README.md b/arc-0003/README.md index 7552094..fe5cab7 100644 --- a/arc-0003/README.md +++ b/arc-0003/README.md @@ -1,8 +1,8 @@ --- arc: 3 -title: Testnet 3.2 +title: Leo and Aleo Instructions authors: @acoglio, @bendyarm, @collinc97, @d0cd, @howardwu -discussion: ARC-0003: Testnet 3.2 +discussion: ARC-0003: Leo and Aleo Instructions topic: Language status: Draft created: 9-29-2022 From 12fd110eca3147855253451498707614efd3566c Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Mon, 3 Oct 2022 10:31:06 -0700 Subject: [PATCH 3/5] update table --- arc-0003/README.md | 96 +++++++++++----------------------------------- 1 file changed, 23 insertions(+), 73 deletions(-) diff --git a/arc-0003/README.md b/arc-0003/README.md index fe5cab7..fad21a6 100644 --- a/arc-0003/README.md +++ b/arc-0003/README.md @@ -1,8 +1,8 @@ --- arc: 3 -title: Leo and Aleo Instructions +title: Leo and Aleo instructions authors: @acoglio, @bendyarm, @collinc97, @d0cd, @howardwu -discussion: ARC-0003: Leo and Aleo Instructions +discussion: ARC-0003: Leo and Aleo instructions topic: Language status: Draft created: 9-29-2022 @@ -12,18 +12,16 @@ created: 9-29-2022 The purpose of this ARC is to unify syntax between Leo and Aleo instructions to make it clear what tools developers have at their disposal. We propose several breaking changes to both Leo and Aleo instructions to achieve this goal. -Leo breaking changes: -* Add `program name.network {}` scope -* Add `interface` abstract type -* Change `circuit` type -> `struct` type -* Change `@program function` -> `transition` - - -Aleo instructions breaking changes: -* Add `interface` abstract type -* Change `interface` type -> `struct` type -* Change `function` -> `transition` -* Change `closure` -> `function` +| Leo V1 —> | Leo V2 & Aleo Instructions V2 | <— Aleo Instructions V1 | +|:-------------------:|:-----------------------------:|:------------------------:| +| ∅ | `program` | `program` | +| ∅ | `interface` | ∅ | +| `mapping` | `mapping` | `mapping` | +| `circuit` | `struct` | `interface` | +| `record` | `record` | `record` | +| `@program function` | `transition` | `function` | +| `function` | `function` | `closure` | +| *name.network* | *name.network* | *name.network* | ## Specification @@ -101,20 +99,7 @@ Interfaces cannot be instantiated on their own. **Aleo instructions** -```rust= -// @howardwu how do you want to write interfaces? -interface fooable; - -mapping balances: - key left as address.public; - value right as u64.public; - -program foo.aleo is fooable; - -mapping balances: - key left as address.public; - value right as u64.public; -``` +The syntax for interfaces in Aleo instructions has not been finalized. Interfaces can be implemented by programs with the `is` keyword. Interfaces cannot be instantiated on their own. @@ -262,51 +247,16 @@ All grammar and documentation repositories will also need to be updated. (The 'V1' and 'V2' designations refer to Leo and Aleo instructions before and after the change proposed by this ARC. They do not refer to official release versions.) -| Leo V1 | Leo V2 | -|-------------------|--------------| -| --- | program | -| ∅ | interface | -| mapping | mapping | -| circuit | struct | -| record | record | -| @program function | transition | -| function | function | -| name.network | name.network | - -| Aleo Instructions V1 | Aleo Instructions V2 | -|----------------------|----------------------| -| program | program | -| ∅ | interface | -| mapping | mapping | -| interface | struct | -| record | record | -| function | transition | -| closure | function | -| name.network | name.network | - - -[//]: # (// Todo: Keep the two tables above or the single table below.) -[//]: # () -[//]: # (| Leo V1 | Leo V2 | Aleo V2 | Aleo V1 |) - -[//]: # (|--------------|--------------|--------------|--------------|) - -[//]: # (| ∅ | program | program | program |) - -[//]: # (| ∅ | interface | interface | ∅ |) - -[//]: # (| mapping | mapping | mapping | mapping |) - -[//]: # (| circuit | struct | struct | interface |) - -[//]: # (| record | record | record | record |) - -[//]: # (| @program | transition | transition | function |) - -[//]: # (| function | function | function | closure |) - -[//]: # (| name.network | name.network | name.network | name.network |) - +| Leo V1 —> | Leo V2 & Aleo Instructions V2 | <— Aleo Instructions V1 | +|:-------------------:|:-----------------------------:|:------------------------:| +| ∅ | `program` | `program` | +| ∅ | `interface` | ∅ | +| `mapping` | `mapping` | `mapping` | +| `circuit` | `struct` | `interface` | +| `record` | `record` | `record` | +| `@program function` | `transition` | `function` | +| `function` | `function` | `closure` | +| *name.network* | *name.network* | *name.network* | ## Security & Compliance From 4fb1fc1ffd7a7df1db8e76bd2dc0ca760b930fd0 Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Mon, 3 Oct 2022 15:29:45 -0700 Subject: [PATCH 4/5] set ARC status to living --- arc-0003/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arc-0003/README.md b/arc-0003/README.md index fad21a6..dc5cabb 100644 --- a/arc-0003/README.md +++ b/arc-0003/README.md @@ -4,7 +4,7 @@ title: Leo and Aleo instructions authors: @acoglio, @bendyarm, @collinc97, @d0cd, @howardwu discussion: ARC-0003: Leo and Aleo instructions topic: Language -status: Draft +status: Living created: 9-29-2022 --- From a3dd38f4fbcdc1bb0a758336a62e7ce100c1fe2a Mon Sep 17 00:00:00 2001 From: collin <16715212+collinc97@users.noreply.github.com> Date: Mon, 3 Oct 2022 16:12:06 -0700 Subject: [PATCH 5/5] update discussion link --- arc-0003/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/arc-0003/README.md b/arc-0003/README.md index dc5cabb..d037383 100644 --- a/arc-0003/README.md +++ b/arc-0003/README.md @@ -1,9 +1,9 @@ --- arc: 3 title: Leo and Aleo instructions -authors: @acoglio, @bendyarm, @collinc97, @d0cd, @howardwu -discussion: ARC-0003: Leo and Aleo instructions -topic: Language +authors: acoglio@aleo.org, collin@aleo.org, ericm@aleo.org, howard@aleo.org, pranav@aleo.org +discussion: https://github.com/AleoHQ/ARCs/discussions/17 +topic: Application status: Living created: 9-29-2022 ---