From 3dcf2ae798672a540dda371beb9bb801b269d819 Mon Sep 17 00:00:00 2001 From: Konstantin Pandl Date: Wed, 4 Oct 2023 13:50:32 +0200 Subject: [PATCH] including all finalize info in the language guide, remove finalize file, update overview links --- documentation/00_overview.md | 1 - documentation/leo/03_language.md | 9 +++--- documentation/leo/10_finalize.md | 54 -------------------------------- 3 files changed, 5 insertions(+), 59 deletions(-) delete mode 100644 documentation/leo/10_finalize.md diff --git a/documentation/00_overview.md b/documentation/00_overview.md index 0603d29d1..e6bfcce93 100644 --- a/documentation/00_overview.md +++ b/documentation/00_overview.md @@ -23,7 +23,6 @@ An index of all pages available in this documentation. - [Leo Code Editor Plugins](./leo/06_tooling.md) - [Leo Examples, Guides, and Developer Resources](./leo/07_resources.md) - [Leo Cheatsheet](./leo/09_cheatsheet.md) -- [Finalize](./leo/10_finalize.md) ### Chapter 2: Leo by Example diff --git a/documentation/leo/03_language.md b/documentation/leo/03_language.md index 7cf85e67b..1eea6516b 100644 --- a/documentation/leo/03_language.md +++ b/documentation/leo/03_language.md @@ -365,17 +365,16 @@ The rules for functions (in the traditional sense) are as follows: ### Finalize Function -A finalize function is declared as `finalize {name}:`. -A finalize function must immediately follow a [transition function](#transition-function), and must have the same name; +A finalize function is declared as `finalize {name}:` and is used to run computations on chain. One of its primary purposes is to initiate or change public on chain state within mappings. A finalize function must immediately follow a transition function, and must have the same name; it is associated with the transition function and is executed on chain, after the zero-knowledge proof of the execution of the associated transition is verified; a finalize function _finalizes_ a transition 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. -More information on finalize functions can be found [here](./10_finalize.md). +Consequently, nodes on the Aleo network execute the code of the finalize function. Only code within finalize blocks, run by nodes on the Aleo Network, updates program mappings. Only a program can write into its own mapping, but all nodes on the Aleo network can read the public state. -```leo showLineNumbers +An example of on-chain state mutation is the transfer_public_to_private transition in the finalize example, which updates the public account mapping (and thus a user's balance) when called. ```leo showLineNumbers program transfer.aleo { @@ -411,6 +410,8 @@ program transfer.aleo { } ``` +If there is no need to create or alter the public on-chain state, finalize functions are not required. + ### Mapping A mapping is declared as `mapping {name}: {key-type} => {value-type}`. diff --git a/documentation/leo/10_finalize.md b/documentation/leo/10_finalize.md deleted file mode 100644 index 064540185..000000000 --- a/documentation/leo/10_finalize.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: finalize -title: Finalize -sidebar_label: Finalize ---- - -A **finalize** function is declared as `finalize {name}:` and is used to run computations on chain. One of its primary purposes is to initiate or change public on chain state within mappings. A finalize function must immediately follow a transition function, and must have the same name; -it is associated with the transition function and is executed on chain, -after the zero-knowledge proof of the execution of the associated transition is verified; -a finalize function _finalizes_ a transition 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. - -Consequently, nodes on the Aleo network execute the code of the finalize function. Only code within finalize blocks, run by nodes on the Aleo Network, updates program mappings. Only a program can write into its own mapping, but all nodes on the Aleo network can read the public state. - -An example of on-chain state mutation is the transfer_public_to_private transition in the finalize example updates the public account mapping (and thus a user's balance) when called. - -```leo showLineNumbers -program transfer.aleo { - // The function `transfer_public_to_private` turns a specified token amount - // from `account` into a token record for the specified receiver. - // - // This function preserves privacy for the receiver's record, however - // it publicly reveals the caller and the specified token amount. - transition transfer_public_to_private( - public receiver: address, - public amount: u64 - ) -> token { - // Produce a token record for the token receiver. - let new: token = token { - owner: receiver, - amount, - }; - - // Return the receiver's record, then decrement the token amount of the caller publicly. - return new then finalize(self.caller, amount); - } - - finalize transfer_public_to_private( - public sender: address, - public amount: u64 - ) { - // Decrements `account[sender]` by `amount`. - // If `account[sender]` does not exist, it will be created. - // If `account[sender] - amount` underflows, `transfer_public_to_private` is reverted. - let current_amount: u64 = Mapping::get_or_use(account, sender, 0u64); - Mapping::set(account, sender, current_amount - amount); - } -} -``` - -If there's no need to create or alter the public on-chain state, finalize functions are not required. - -[Link back to Leo language guide](./03_language.md#finalize-function) \ No newline at end of file