Merge pull request #569 from ProvableHQ/mohammadfawaz/3.5-updates

Some Leo 3.5 updates

Author: IGI-111

documentation/language/02_structure.md

@@ -135,12 +135,15 @@ mapping account: address => u64;
 ```
 
 ### Storage
-A storage variable is declared as `storage {name}: {type}`.  Storage variables contain singleton values.  They are declared at program scope and are stored on chain, similar to mappings.
+A storage variable is declared as `storage {name}: {type}`. Storage variables contain singleton values. They are declared at program scope and are stored on chain, similar to mappings.
+
 ```leo
 // On-chain storage of an `counter` storage variable of type u32,
 storage counter: u32;
 ```
+
 A storage vector is declared as `storage {name}: [{type}]`.  Storage vectors contain dynamic lists of values of a given type.  They are declared at program scope and are stored on chain, similar to mappings.
+
 ```leo
 // On-chain storage of an `accounts` storage vector of type address,
 storage accounts: [address];
@@ -176,4 +179,4 @@ record Token {
     // The token amount.
     amount: u64,
 }
-```
+```

documentation/language/03_data_types.md

@@ -126,6 +126,12 @@ program test.aleo {
 }
 ```
 
+Signature literals can be also be used. For example:
+
+```leo
+let sig: signature = sign195m229jvzr0wmnshj6f8gwplhkrkhjumgjmad553r997u7pjfgpfz4j2w0c9lp53mcqqdsmut2g3a2zuvgst85w38hv273mwjec3sqjsv9w6uglcy58gjh7x3l55z68zsf24kx7a73ctp8x8klhuw7l2p4s3aq8um5jp304js7qcnwdqj56q5r5088tyvxsgektun0rnmvtsuxpe6sj
+```
+
 ## Composite Types
 
 ### Arrays
@@ -223,9 +229,9 @@ transition baz(foo: u8, bar: u8) -> u8 {
 
 ### Structs
 
-Struct types are declared and constructed with a familiar syntax. Note that there is a global namespace for struct
-types across your program and its dependencies. If a dependency declares a struct type `T`, you may access that type
-without any qualifier.
+Struct types are declared and constructed with a familiar syntax.
+
+Structs defined within a program can be referenced by their name. Structs defined in other programs must be referenced using the fully qualified form `program_name.aleo/StructName`.
 
 ```leo
 program test.aleo {
@@ -244,7 +250,17 @@ program test.aleo {
 }
 ```
 
-As of v3.0.0, Leo now supports **const generics** for struct types:
+Structs defined in external programs can be referenced and constructed using their fully qualified name:
+
+```leo
+let s: external_program.aleo/S2 = external_program.aleo/S2 {
+    x: 1field,
+    y: 2u32,
+};
+```
+
+Leo supports **const generics** for struct types:
+
 ```leo
 struct Matrix::[N: u32, M: u32] {
     data: [field; N * M],
@@ -253,7 +269,8 @@ struct Matrix::[N: u32, M: u32] {
 // Usage
 let m = Matrix::[2, 2] { data: [0, 1, 2, 3] };
 ```
-Note that generic structs cannot currently be imported outside a program, but can be declared and used in submodules. Acceptable types for const generic parameters include integer types, `bool`,  `scalar`, `group`, `field`, and `address`.
+
+Acceptable types for const generic parameters include integer types, `bool`, `scalar`, `group`, `field`, and `address`. Const generic structs may be declared and used within a program and its submodules, but they cannot currently be imported from external programs.
 
 ### Records
 

documentation/language/06_programs.md

@@ -75,26 +75,33 @@ Mapping operations are only allowed in an [async function](#async-function) or a
 
 ## Storage Variables
 
-Storage variables behave similar to option types.  There are several functions available to query and modify singleton storage variables.  The examples below will reference the following:
+Storage variables behave similar to option types. There are several functions available to query and modify singleton storage variables.  The examples below will reference the following:
 ```leo
 storage counter: u64;
 ```
 
 ### Querying
-To query the value currrently stored at `counter`:
+To query the value currently stored at `counter`:
+
 ```leo
 counter.unwrap();
 ```
+
 Note that if `counter` has not been initialized, then the program will fail to execute.  To query the value with a fallback for this case:
+
 ```leo
 counter.unwrap_or(fallback_value);
 ```
+
 ### Modifying
 To set a value for `counter`:
+
 ```leo
 counter = 5u64;
 ```
+
 To unset the value at `counter`:
+
 ```leo
 counter = none;
 ```
@@ -115,51 +122,105 @@ program storage_variable.aleo {
 
 }
 ```
+
 :::info
-Storage variable operations are only allowed in an [async function](#async-function) or async block.
+Storage variable operations are only allowed in an [async function](#async-function) or `async` block.
 :::
 
+### External Access
+
+Storage variables defined in another program can be accessed using the fully qualified form `program_name.aleo/storage_name`. External storage variables are **read-only** and cannot be modified.
+
+For example, suppose another program defines the following storage variable:
+
+```leo
+program external_program.aleo {
+    storage counter: u64;
+
+    ...
+}
+```
+
+You may query this value from your program using:
+
+```leo
+let value: u64 = external_program.aleo/counter.unwrap();
+```
+
+As with local storage variables, calling `unwrap()` will cause execution to fail if the storage variable has not been initialized. To safely query the value with a fallback:
+
+```leo
+let value: u64 = external_program.aleo/counter.unwrap_or(0u64);
+```
+
+External storage variables cannot be assigned to or unset. The following operations are invalid:
+
+```leo
+external_program.aleo/counter = 5u64;   // invalid
+external_program.aleo/counter = none;   // invalid
+```
 
 ## Storage Vectors
 
-Storage vectors behave like dynamic arrays of values of a given types.  There are several functions available to query and modify storage vectors.  The examples below will reference the following:
+Storage vectors behave like dynamic arrays of values of a given type. Several functions are available to query and modify storage vectors. The examples below reference the following declaration:
+
 ```leo
 storage id_numbers: [u64];
 ```
 
 ### Querying
-To query the element currrently stored in `id_numbers` at index `idx`:
+
+To query the element currently stored in `id_numbers` at index `idx`:
+
 ```leo
 id_numbers.get(idx);
 ```
+
+This returns `u64?`. If `idx` is out of bounds, the result is `none`.
+
 To get the current length of `id_numbers`:
+
 ```leo
 id_numbers.len();
 ```
+
+This always returns a `u32` and cannot fail.
+
 ### Modifying
+
 To set an element at index `idx` in `id_numbers`:
+
 ```leo
 id_numbers.set(idx, value);
 ```
+
 To push an element onto the end of `id_numbers`:
+
 ```leo
 id_numbers.push(value);
 ```
+
 To pop and return the last element of `id_numbers`:
+
 ```leo
 id_numbers.pop();
 ```
+
 To remove the element at index `idx`, return it, and replace it with the final element of `id_numbers`:
+
 ```leo
 id_numbers.swap_remove(idx);
 ```
-To clear the every element in `id_numbers`:
+
+To clear every element in `id_numbers`:
+
 ```leo
-id_numbers.clear()
+id_numbers.clear();
 ```
+
 :::note
-- `clear()` does not actually remove any values from the vector. It just sets the length to 0.
-- Similarly `swap_remove()` and `pop()` do not actually remove values either. They just reduce the length by 1 to make sure the last element is no longer accessible.
+- `clear()` does not actually remove any values from the vector. It simply sets the length to `0`.
+- Similarly, `swap_remove()` and `pop()` do not physically remove values. They reduce the length by `1`, ensuring the final element is no longer accessible.
 :::
 
 ### Usage
@@ -176,7 +237,6 @@ program storage_vector.aleo {
         id_numbers.push(new_id);
     }
 
-
     async transition remove_id(idx: u32) -> Future {
         return remove_id_onchain(idx);
     }
@@ -186,10 +246,39 @@ program storage_vector.aleo {
     }
 }
 ```
+
 :::info
-Storage vector operations are only allowed in an [async function](#async-function) or async block.
+Storage vector operations are only allowed in an [async function](#async-function) or `async` block.
 :::
 
+### External Access
+
+Storage vectors defined in another program can be accessed using the fully qualified form `program_name.aleo/storage_name`. External storage vectors are **read-only** and cannot be modified.
+
+For example, suppose another program defines the following storage vector:
+
+```leo
+program external_program.aleo {
+    storage id_numbers: [u64];
+}
+```
+
+You may query elements or the length of this vector from your program:
+
+```leo
+let first: Option<u64> = external_program.aleo/id_numbers.get(0u32);
+let length: u32 = external_program.aleo/id_numbers.len();
+```
+
+External storage vectors cannot be modified. The following operations are invalid:
+
+```leo
+external_program.aleo/id_numbers.push(5u64);        // invalid
+external_program.aleo/id_numbers.set(0u32, 5u64);   // invalid
+external_program.aleo/id_numbers.pop();             // invalid
+external_program.aleo/id_numbers.swap_remove(0u32); // invalid
+external_program.aleo/id_numbers.clear();           // invalid
+```
 
 ## Functions
 
@@ -381,9 +470,9 @@ snarkVM imposes the following limits on Aleo programs:
 
 Some other protocol-level limits to be aware of are:
 - **the maximum transaction size is 128 KB.** If your program exceeds this, perhaps by requiring large inputs or producing large outputs, consider optimizing the data types in your Leo code.
-- **the maxmimum number of micro-credits your transaction can consume for on-chain execution is `100_000_000`.**. If your program exceeds this, consider optimizing on-chain components of your Leo code.
+- **the maximum number of micro-credits your transaction can consume for on-chain execution is `100_000_000`.**. If your program exceeds this, consider optimizing on-chain components of your Leo code.
 
-As with the above restructions. these limits can only be increased via the governance process.
+As with the above restrictions, these limits can only be increased via the governance process.
 
 ## Compiling Conditional On-Chain Code
 Consider the following Leo transition.

documentation/language/08_cheatsheet.md

@@ -156,6 +156,8 @@ let sender_address: address = msg.sender;
 let object_value: u64 = msg.object;
 ```
 
+An struct `ExternalStruct` defined in program `external_program.aleo` can be referred outside the program using the syntax `external_program.aleo/ExternalStruct`.
+
 ### Const Generics
 ```leo
 struct Matrix::[N: u32, M: u32] {
@@ -482,4 +484,4 @@ let ecdsa_eth: bool = ECDSA::verify_keccak256_eth(sig, eth_addr, msg); // Verify
 
 let ecdsa_digest: bool = ECDSA::verify_digest(sig, addr, digest); // Verify an ECDSA signature against an ECDSA public key and a prehashed message
 let ecdsa_digest_eth: bool = ECDSA::verify_digest_eth(sig, eth_addr, digest); Verify an ECDSA signature against an Ethereum address and a prehashed message
-```
+```

documentation/language/programs_in_practice/limitations.md

@@ -24,7 +24,7 @@ Some other protocol-level limits to be aware of are:
 - **the maximum transaction size is 128 KB.** If your program exceeds this, perhaps by requiring large inputs or producing large outputs, consider optimizing the data types in your Leo code.
 - **the maximum number of micro-credits your transaction can consume for on-chain execution is `100_000_000`.**. If your program exceeds this, consider optimizing on-chain components of your Leo code.
 
-As with the above restructions. these limits can only be increased via the governance process.
+As with the above restrictions, these limits can only be increased via the governance process.
 
 ## Compiling Conditional On-Chain Code
 Consider the following Leo transition.