Skip to content

Commit

Permalink
add some details to field/group/scalar doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@bendyarm
bendyarm committed Aug 28, 2023
1 parent c17eca0 commit 46d05c6
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 61 deletions.
90 changes: 49 additions & 41 deletions documentation/aleo/03_language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ There is no `undefined` or `null` value in Aleo instructions. When assigning a n
Expressions in Aleo instructions are always **passed by value**, which means their values are always copied when they are used as function inputs or in right sides of assignments.

### Register based
There are no variable names in Aleo instructions.
There are no variable names in Aleo instructions.
All variables are stored in registers denoted `rX` where `X` is a non-negative whole number starting from 0 `r0, r1, r2, etc.`.

## Data Types and Values
Expand Down Expand Up @@ -42,27 +42,35 @@ Higher bit length integers generate more constraints in the circuit, which can s

### Field Elements

Aleo instructions supports the `field` type for the base field elements of the elliptic curve.
These are unsigned integers below the modulus of the base field.
Aleo instructions supports the `field` type for elements of the base field of the elliptic curve.
These are unsigned integers less than the modulus of the base field, so the largest field element
is `8444461749428370424248824938781546531375899335154063827935233455917409239040field`.

```aleo
function main:
input r0: field.private;
```

### Group Elements

The set of affine points on the elliptic curve passed into the Aleo instructions compiler forms a group.
Leo supports a subgroup of this group, generated by a generator point, as a primitive data type.
Group elements are special since their values can be defined from the x-coordinate of a coordinate pair, such as
`0group`. The group type keyword `group` must be used when specifying a group value.
The curve is a Twisted Edwards curve with `a = -1` and `d = 3021`.
Aleo instructions supports a subgroup of the group, generated by a generator point, as a primitive data type.
A group element is denoted by the x-coordinate of its point; for example,
`2group` means the point `(2, 5553594316923449299484601589326170487897520766531075014687114064346375156608)`.
The generator point is `1540945439182663264862696551825005342995406165131907382295858612069623286213group`.

```aleo
function main:
input r0: group.private;
```

### Scalar Elements
Aleo instructions supports the `scalar` type for scalar field elements of the elliptic curve subgroup.
These are unsigned integers below the modulus of the scalar field.

Aleo instructions supports the `scalar` type for elements of the scalar field defined by the elliptic curve subgroup.
These are unsigned integers less than the modulus of the scalar field, so the largest scalar is
`2111115437357092606062206234695386632838870926408408195193685246394721360382scalar`.

```aleo
function main:
input r0: scalar.private;
Expand Down Expand Up @@ -103,7 +111,7 @@ program _foo.aleo; // invalid

### Import

An import is declared as `import {ProgramID};`.
An import is declared as `import {ProgramID};`.
Imports fetch other declarations by their program ID and bring them into the current file scope.
You can import dependencies that are downloaded to the `imports` directory.

Expand All @@ -115,7 +123,7 @@ program hello.aleo;

### Function

A function is declared as `function {name}:`.
A function is declared as `function {name}:`.
Functions contain instructions that can compute values.
Functions must be in a program's current scope to be called.

Expand All @@ -129,18 +137,18 @@ function foo:

#### Function Inputs

A function input is declared as `input {register} as {type}.{visibility};`.
A function input is declared as `input {register} as {type}.{visibility};`.
Function inputs must be declared just after the function name declaration.

```aleo showLineNumbers
// The function `foo` takes a single input `r0` with type `field` and visibility `public`.
function foo:
input r0 as field.public;
input r0 as field.public;
```

#### Function Outputs

A function output is declared as `output {register} as {type}.{visibility};`.
A function output is declared as `output {register} as {type}.{visibility};`.
Function outputs must be declared at the end of the function definition.

```aleo showLineNumbers
Expand All @@ -150,13 +158,13 @@ Function outputs must be declared at the end of the function definition.

#### Call a Function
In the Aleo protocol, calling a function creates a transition that can consume and produce records on-chain.
Use the `aleo run` CLI command to pass inputs to a function and execute the program.
Use the `aleo run` CLI command to pass inputs to a function and execute the program.
In Testnet3, program functions cannot call other internal program functions.
If you would like to develop "helper functions" that are called internally within a program, try writing a `closure`.

#### Call an Imported Function
Aleo programs can externally call other Aleo programs using the `call {program}/{function} {register} into {register}` instruction.
```aleo
```aleo
import foo.aleo;
program bar.aleo;
Expand All @@ -169,7 +177,7 @@ function call_external:

### Closure

A closure is declared as `closure {name}:`.
A closure is declared as `closure {name}:`.
Closures contain instructions that can compute values.
Closures are helper functions that cannot be executed directly. Closures may be called by other functions.

Expand All @@ -183,7 +191,7 @@ closure foo:

#### Call a Closure
Aleo programs can internally call other Aleo closures using the `call {name} {register} into {register}` instruction.
```aleo
```aleo
program bar.aleo;
function call_internal:
Expand All @@ -195,7 +203,7 @@ function call_internal:

### Struct

A struct is a data type declared as `struct {name}:`.
A struct is a data type declared as `struct {name}:`.
Structs contain component declarations `{name} as {type}`.

```aleo showLineNumbers
Expand All @@ -217,9 +225,9 @@ function new_array3:

### Record

A [record](../concepts/02_records.md) type is declared as `record {name}:`.
Records contain component declarations `{name} as {type}.{visibility};`.
Record data structures must contain the `owner` declaration as shown below.
A [record](../concepts/02_records.md) type is declared as `record {name}:`.
Records contain component declarations `{name} as {type}.{visibility};`.
Record data structures must contain the `owner` declaration as shown below.
When passing a record as input to a program function the `_nonce as group.{visibility}` declaration is also required.

```aleo showLineNumbers
Expand All @@ -244,7 +252,7 @@ function new_token:

### Mapping

A mapping is declared as `mapping {name}:`.
A mapping is declared as `mapping {name}:`.
Mappings contain key-value pairs.
Mappings must be defined within a program scope.
Mappings are stored publicly on-chain. It is not possible to store data privately in a mapping.
Expand Down Expand Up @@ -279,14 +287,14 @@ finalize transfer_public:
input r1 as address.public;
// Input the amount.
input r2 as u64.public;
// Decrements `account[r0]` by `r2`.
// If `account[r0]` does not exist, 0u64 is used.
// If `account[r0] - r2` underflows, `transfer_public` is reverted.
get.or_use account[r0] 0u64 into r3;
sub r3 r2 into r4;
set r4 into account[r0];
// Increments `account[r1]` by `r2`.
// If `account[r1]` does not exist, 0u64 is used.
// If `account[r1] + r2` overflows, `transfer_public` is reverted.
Expand All @@ -309,13 +317,13 @@ A remove command that removes a key-value pair from a mapping, e.g. `remove acco
### Finalize
A finalize is declared as `finalize {name}:`.
A finalize is declared as `finalize {name}:`.
A finalize must immediately follow a [function](#function), and must have the same name;
it is associated with the function and is executed on chain,
after the zero-knowledge proof of the execution of the associated function is verified;
a finalize *finalizes* a function on chain.
Upon success of the finalize function, the program logic is executed.
Upon failure of the finalize function, the program logic is reverted.
a finalize *finalizes* a function on chain.
Upon success of the finalize function, the program logic is executed.
Upon failure of the finalize function, the program logic is reverted.
```aleo showLineNumbers
// The `transfer_public_to_private` function turns a specified amount
Expand All @@ -328,13 +336,13 @@ function transfer_public_to_private:
input r0 as address.public;
// Input the amount.
input r1 as u64.public;
// Construct a record for the receiver.
cast r0 r1 into r2 as credits.record;
// Output the record of the receiver.
output r2 as credits.record;
// Decrement the balance of the sender publicly.
finalize self.caller r1;
Expand All @@ -343,15 +351,15 @@ finalize transfer_public_to_private:
input r0 as address.public;
// Input the amount.
input r1 as u64.public;
// Retrieve the balance of the sender.
// If `account[r0]` does not exist, 0u64 is used.
get.or_use account[r0] 0u64 into r2;
// Decrements `account[r0]` by `r1`.
// If `r2 - r1` underflows, `trasfer_public_to_private` is reverted.
sub r2 r1 into r3;
// Updates the balance of the sender.
set r3 into account[r0];
```
Expand All @@ -361,7 +369,7 @@ finalize transfer_public_to_private:
The following commands are supported in Aleo Instructions to provide additional program functionality.

#### self.caller
The `self.caller` command returns the address of the caller of the program.
The `self.caller` command returns the address of the caller of the program.
This can be useful for managing access control to a program.
In the above example, the `transfer_public_to_private` function decrements the balance of the sender publicly using `self.caller`.

Expand All @@ -376,9 +384,9 @@ assert.eq block.height 100u64;

#### rand.chacha

The `rand.chacha` command returns a random number generated by the [ChaCha20 algorithm](http://cr.yp.to/chacha.html).
This command supports sampling a random `address`, `boolean`, `field`, `group`, `i8`, `i16`, `i32`, `i64`, `i128`, `u8`, `u16`, `u32`, `u64`, `u128`, and `scalar`.
Up to two additional seeds can be provided to the `rand.chacha` command.
The `rand.chacha` command returns a random number generated by the [ChaCha20 algorithm](http://cr.yp.to/chacha.html).
This command supports sampling a random `address`, `boolean`, `field`, `group`, `i8`, `i16`, `i32`, `i64`, `i128`, `u8`, `u16`, `u32`, `u64`, `u128`, and `scalar`.
Up to two additional seeds can be provided to the `rand.chacha` command.
Currently, only ChaCha20 is supported, however, in the future, other random number generators may be supported.

```aleo
Expand Down Expand Up @@ -418,7 +426,7 @@ Checkout the [Aleo Instructions opcodes](./04_opcodes.md) for a full list of sup

#### Commit

Aleo Instructions supports the following syntax for committing to standard types.
Aleo Instructions supports the following syntax for committing to standard types.
Note that the `commit` command requires any type as the first argument, and a `scalar` as the second argument.
```aleo
commit.bhp256 r0 r1 into r2 as address;
Expand All @@ -433,8 +441,8 @@ commit.ped128 ...;
Checkout the [Aleo Instructions opcodes](./04_opcodes.md) for a full list of supported commitment algorithms.

#### position, branch.eq, branch.neq
The `position` command, e.g. `position exit`, indicates a point to branch execution to.
The `branch.eq` command, e.g. `branch.eq r0 r1 to exit`, which branches execution to the position indicated by `exit` if `r0` and `r1` are equal.
The `position` command, e.g. `position exit`, indicates a point to branch execution to.
The `branch.eq` command, e.g. `branch.eq r0 r1 to exit`, which branches execution to the position indicated by `exit` if `r0` and `r1` are equal.
The `branch.neq` command, e.g. `branch.neq r0 r1 to exit`, which branches execution to the position indicated by `exit` if `r0` and `r1` are not equal.

** Example **
Expand Down
45 changes: 25 additions & 20 deletions documentation/leo/03_language.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Higher bit length integers generate more constraints in the circuit, which can s

#### A Note on Leo Integers

Leo will not default to an integer type. The definition of a integer **must** include an explicit type.
Leo will not default to an integer type. The definition of a integer **must** include an explicit type.
**Type casting is supported as of Leo v1.8.2**

```leo
Expand All @@ -57,23 +57,26 @@ let b: u8 = 2; // implicit type -- not supported

### Field Elements

Leo supports the `field` type for the base field elements of the elliptic curve.
These are unsigned integers below the modulus of the base field.
Leo supports the `field` type for elements of the base field of the elliptic curve.
These are unsigned integers less than the modulus of the base field. Showing the
smallest and largest field elements.

```leo
let a: field = 1field;
let b: field = 21888242871839275222246405745257275088548364400416034343698204186575808495617field;
let a: field = 0field;
let b: field = 8444461749428370424248824938781546531375899335154063827935233455917409239040field;
```

### Group Elements

The set of affine points on the elliptic curve passed into the Leo compiler forms a group.
Leo supports a subgroup of this group, generated by a generator point, as a primitive data type.
Group elements are special since their values can be defined from the x-coordinate of a coordinate pair, such as
`0group`. The group type keyword `group` must be used when specifying a group value.
The curve is a Twisted Edwards curve with `a = -1` and `d = 3021`.
Leo supports a subgroup of the group, generated by a generator point, as a primitive data type.
A group element is denoted by the x-coordinate of its point; for example,
`2group` means the point `(2, 5553594316923449299484601589326170487897520766531075014687114064346375156608)`.

```leo
let b: group = 0group; // the point with 0 x-coordinate
let a: group = 0group; // the point with 0 x-coordinate, (0, 1)
let b: group = 1540945439182663264862696551825005342995406165131907382295858612069623286213group; // the generator point
```

The aforementioned generator point can be obtained via a constant associated to the `group` type.
Expand All @@ -84,11 +87,13 @@ let g: group = group::GEN; // the group generator

### Scalar Elements

Leo supports the `scalar` type for scalar field elements of the elliptic curve subgroup.
These are unsigned integers below the modulus of the scalar field.
Leo supports the `scalar` type for elements of the scalar field defined by the elliptic curve subgroup.
These are unsigned integers less than the modulus of the scalar field. Showing the smallest and largest
scalars.

```leo
let a: scalar = 1scalar;
let a: scalar = 0scalar;
let b: scalar = 2111115437357092606062206234695386632838870926408408195193685246394721360382scalar;
```

### Addresses
Expand Down Expand Up @@ -391,7 +396,7 @@ mapping account: address => u64;
#### Mapping Operations

The mapping struct allows the programmer to apply updates to a program mapping data structure by calling one of the
following functions.
following functions.

:::info
Mapping operations are only allowed in a [finalize function](#finalize-function).
Expand Down Expand Up @@ -423,8 +428,8 @@ If the value at `addr` does not exist, then the program will fail to execute.

#### get_or_use

A get command that uses the provided default in case of failure,
e.g. `let current_value: u64 = Mapping::get_or_use(counter, addr, 0u64);`
A get command that uses the provided default in case of failure,
e.g. `let current_value: u64 = Mapping::get_or_use(counter, addr, 0u64);`
Gets the value stored at `addr` in `counter` and stores the result in `current_value`.
If the key is not present, `0u64` is stored in `counter` and stored in `current_value`.

Expand Down Expand Up @@ -621,7 +626,7 @@ program test.aleo {

### Hash

Leo supports the following hashing algorithms: `BHP256`, `BHP512`, `BHP768`, `BHP1024`, `Pedersen64`, `Pedersen128`, `Poseidon2`, `Poseidon4`, `Poseidon8`
Leo supports the following hashing algorithms: `BHP256`, `BHP512`, `BHP768`, `BHP1024`, `Pedersen64`, `Pedersen128`, `Poseidon2`, `Poseidon4`, `Poseidon8`
The output type of a commitment function is specified in the function name. e.g. `hash_to_group` will return a `group` type.
Hash functions take any type as an argument.

Expand All @@ -634,8 +639,8 @@ let c: group = Poseidon2::hash_to_group(1field);

### Commit

Leo supports the following commitment algorithms: `BHP256`, `BHP512`, `BHP768`, `BHP1024`, `Pedersen64`, `Pedersen128`
The output type of a commitment function is specified in the function name. e.g. `commit_to_group` will return a `group` type.
Leo supports the following commitment algorithms: `BHP256`, `BHP512`, `BHP768`, `BHP1024`, `Pedersen64`, `Pedersen128`
The output type of a commitment function is specified in the function name. e.g. `commit_to_group` will return a `group` type.
The first argument can be any type. The second argument must be a `field` type and is used as a blinding factor.

```leo showLineNumbers
Expand All @@ -647,8 +652,8 @@ let b: address = Pedersen64::commit_to_address(1u128, 2field);

### Random

Leo supports the `ChaCha` random number generation algorithm.
The output type of a random function is specified in the function name. e.g. `rand_group` will return a `group` type.
Leo supports the `ChaCha` random number generation algorithm.
The output type of a random function is specified in the function name. e.g. `rand_group` will return a `group` type.

:::info
Random functions are only allowed in a [finalize function](#finalize-function).
Expand Down

0 comments on commit 46d05c6

Please sign in to comment.