diff --git a/examples/sudt-script/README.md b/examples/sudt-script/README.md index 447261b19..341adbdbd 100644 --- a/examples/sudt-script/README.md +++ b/examples/sudt-script/README.md @@ -1,6 +1,6 @@ # sudt-script -TODO: Write this readme +This is a Simple User-Defined Token (SUDT) Script. It allows users to create, manage, and transfer custom tokens on CKB blockchain. [Full tutorial](https://docs.nervos.org/docs/script/sudt-script) *This project was bootstrapped with [ckb-script-templates].* diff --git a/examples/sudt-script/contracts/sudt/README.md b/examples/sudt-script/contracts/sudt/README.md index cd4f05ef6..0175ecf17 100644 --- a/examples/sudt-script/contracts/sudt/README.md +++ b/examples/sudt-script/contracts/sudt/README.md @@ -1,6 +1,6 @@ # sudt -TODO: Write this readme +This is a Simple User-Defined Token (SUDT) Script. It allows users to create, manage, and transfer custom tokens on CKB blockchain. *This contract was bootstrapped with [ckb-script-templates].* diff --git a/website/docs/script/sudt-script.mdx b/website/docs/script/sudt-script.mdx index c067271ce..81d14164f 100644 --- a/website/docs/script/sudt-script.mdx +++ b/website/docs/script/sudt-script.mdx @@ -18,12 +18,12 @@ import ScriptTools from "./_ScriptTools.mdx"; tools={ScriptHeaders.sudt.tools} /> -User Defined Token(UDT) is a fungible token standard on CKB blockchain. +User-Defined Token (UDT) is a fungible token standard on CKB blockchain. -In this tutorial, we will create a UDT Script which is a simplify version of [XUDT standard](/docs/common-scripts/xudt) -to helps you gain better understanding of how fungible token works on CKB. +In this tutorial, we will create a UDT Script, a simplified version of [XUDT standard](/docs/common-scripts/xudt) +to help you better understand how fungible tokens work on CKB. -It is highly recommend to go through the dApp tutorial [Create a Fungible Token](/docs/dapp/create-token) first before writing your own UDT Script. +It is highly recommended to go through the dApp tutorial [Create a Fungible Token](/docs/dapp/create-token) first before writing your own UDT Script. The full code of the UDT Script in this tutorial can be found at [Github](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script). @@ -39,21 +39,20 @@ lock: ``` Here the issuer's `Lock Script Hash` works like the unique ID for the custom token. -Different Lock Script Hash means a different kind of token issued by different owner. -It is also used as a checkpoint to tell that a transaction is triggered by the token issuer -or a regular token holder to apply different security validation. +Different Lock Script Hashes correspond to different types of token issued by different owners. +This hash is also used to determine if a transaction is initiated by the token issuer or a regular token holder, to apply different security checks. -- For the token owner, they can perform any operation. -- For regular token holders, the UDT Script ensures that the amount in the output cells does not - exceed the amount in the input cells. - For the more detail explanation of UDT idea, - please refer to [create-a-token](/docs/dapp/create-token) or [sudt RFC](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0025-simple-udt/0025-simple-udt.md) +- **Token Owner**: Can perform any operation. +- **Regular Holders**: The UDT Script ensures that the amount in the output Cells does not + exceed that in the input Cells. + For a more detailed explanation, + please refer to [Create a Fungible Token](/docs/dapp/create-token) or [RFC0025: Simple UDT](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0025-simple-udt/0025-simple-udt.md) -Now let's create a new project to build the UDT Script. We will use [offckb](https://github.com/ckb-ecofund/offckb) and [ckb-script-templates](https://github.com/cryptape/ckb-script-templates) for this purpose. +Now, let's create a new project to build the UDT Script. We will use [OFFCKB](https://github.com/ckb-ecofund/offckb) and [ckb-script-templates](https://github.com/cryptape/ckb-script-templates). -### Init a Script Project +### Initialize a Script Project -Let's run the command to generate a new Script project called `sudt-script`(shorthand for simple UDT): +Let's run the command to generate a new Script project called `sudt-script`(short for simple UDT): ```mdx-code-block @@ -119,7 +118,7 @@ make generate ``` -Our project is successfully setup! You can run `tree .` to show the project structure: +Our project is successfully setup. You can run `tree .` to view the project structure: ```mdx-code-block @@ -164,19 +163,19 @@ tree . ``` -Here's a little introduction: `contracts/sudt/src/main.rs` contains the source code of the sudt Script, while `tests/tests.rs` provides unit tests for our Scripts. We will introduce the tests after we wrote the Script. +`contracts/sudt/src/main.rs` contains the source code of the sUDT Script, and `tests/tests.rs` provides the unit tests for our Scripts. We will introduce the tests after completing the Script. -### Implement SUDT Script Logic +### Implement sUDT Script Logic -The sudt Script is implemented in [contracts/sudt/src/main.rs](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script/contracts/sudt/src/main.rs). This script is designed to manage the transfer of UDTs on the CKB blockchain. +The sUDT Script is implemented in [contracts/sudt/src/main.rs](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script/contracts/sudt/src/main.rs). This script is designed to manage the transfer of UDTs on the CKB blockchain. -Let's break down the high-level logic of how this script works: +Let's break down the high-level logic of how this Script works: -1. **Owner Mode Check**: The script first checks if it is being executed in owner mode. This is important because if the script is running in owner mode, it means the owner has special permissions, and the script can return success immediately without further checks. +1. **Owner Mode Check**: The Script first checks if it is being executed in owner mode. This is important because running in owner mode means that the owner has special permissions, allowing the Script to return success immediately without further checks. -2. **Input and Output Amount Validation**: Next, the script collects the total amounts of UDTs from both input and output cells. It ensures that the total amount of UDTs being sent (outputs) does not exceed the amount being received (inputs). This is crucial for maintaining the integrity of the token transfers. +2. **Input and Output Amount Validation**: Next, the Script collects the total UDTs amounts from the input and output Cells to ensure that the UDTs being sent (outputs) do not exceed that being received (inputs). This is crucial for maintaining the integrity of token transfers. -Here’s a snippet of the code that illustrates these checks: +Here’s the code snippet illustrating these checks: ```rust pub fn program_entry() -> i8 { @@ -210,22 +209,24 @@ pub fn program_entry() -> i8 { } ``` -3. **Error Handling**: The script also includes robust error handling. It defines a custom `Error` enum to manage various error conditions, such as when the input amount is invalid or when there are issues with encoding. This helps ensure that any problems are clearly communicated. +3. **Error Handling**: The Script includes robust error handling through a custom `Error` enum to manage various error conditions, such as invalid input or encoding issues. This ensures clear communication of any problems. -This implementation ensures that UDT transactions are validated correctly, maintaining the integrity of token transfers on the CKB blockchain. By checking both the owner mode and the amounts, the script helps prevent errors and ensures smooth operation. +Together, this implementation validates UDT transactions effectively, maintaining the integrity of token transfers on the CKB blockchain. By checking both the owner mode and the amounts, the Script helps preventing errors and promotes smooth operation. ### Collecting UDT Amount -In the sudt Script, the functions `collect_inputs_amount` and `collect_outputs_amount` play a crucial role in gathering the total amounts of UDTs from the respective input and output cells. +In the sUDT Script, the `collect_inputs_amount` and `collect_outputs_amount` functions play a crucial role in gathering the total amounts of UDTs from the respective input and output cells. Here’s how they work: -Both functions iterate through the relevant cells and collect the `cell_data` to calculate the total UDT amount. This is done using the following syscalls: +Both functions iterate through the relevant Cells and collect the `cell_data` to calculate the total UDT amount, done with the following syscalls: -- **`Source::GroupInput`**: This ensures that only the cells with the same script as the current running script are iterating -- **`Source::GroupOutput`**: Similarly, this syscall only the cells with the same script as the current running script are iterating +- **`Source::GroupInput`** +- **`Source::GroupOutput`** -By using these specific [sources](/docs/script/syscalls-for-script#source), the script avoids issues related to different UDT cell types, ensuring that only the appropriate cells are processed. This is particularly important in a blockchain environment where multiple UDTs may exist, and we want to ensure that the calculations are accurate and relevant to the current UDT Script. +For source group input and output respectively, they ensure that only the Cells with the same Script as the current running Script are involved in the iteration. + +By using these specific [sources](/docs/script/syscalls-for-script#source), the Script avoids issues related to different UDT Cell types, ensuring that only the appropriate Cells can be processed. This is particularly important in a blockchain environment where multiple UDTs may exist, to ensure accurate iteration of the relevant UDT Script. Here’s a brief look at how these functions are implemented: @@ -263,18 +264,18 @@ fn collect_outputs_amount() -> Result { } ``` -In summary, these functions are essential for accurately calculating the total UDT amounts involved in the transaction while ensuring that only the relevant cells are considered, thus maintaining the integrity of the UDT transfer process. +In summary, these functions are essential for the accurate calculation of the total UDT amounts involved in the transaction, while ensuring that only the relevant Cells are considered, thus maintaining the integrity of the UDT transfer process. Full code: [contracts/sudt/src/main.rs](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script/contracts/sudt/src/main.rs) -### Writing Test For UDT Script +### Write Tests for UDT Script -Testing is a crucial part of developing any smart contract, including the sudt script. +Testing is a crucial part of developing any smart contract, including the sUDT Script. The `test_transfer_sudt` test case is designed to simulate a transfer of UDTs from one address to another. -It sets up the necessary environment, including creating input and output cells, and then invokes the sudt Script to perform the transfer. +It sets up the necessary environment, including creating input and output Cells, then invoking the sUDT Script to perform the transfer. The test checks whether the transfer transaction is successfully verified. -Here’s a code of the `transfer_sudt` test case: +Here’s the code for the `transfer_sudt` test case: ```rust #[test] @@ -352,15 +353,15 @@ fn test_transfer_sudt() { In this test case: -- We deploy the sudt Script we wrote and use it to build cell's type script. +- We deploy the sUDT Script we wrote and use it to build the Cell's Type Script. - We set up the initial conditions by defining the valid input and output amounts. -- Finally, We build the full transaction and ensure that the transaction can be verified. +- Finally, we build the full transaction and ensure its validity. -Notice that in the type script args we use a random bytes which is 42 indicating that we are not under the `owner_mode` in the `test_transfer_sudt` test case. +Notice that in the Type Script args we use a random bytes which is 42 indicating that we are not under the `owner_mode` in the `test_transfer_sudt` test case. -For ownermode testcase, you can checkout the [full tests code](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script/contracts/sudt/tests/src/tests.rs) for reference. +For owner mode test case, refer to the [full tests code](https://github.com/nervosnetwork/docs.nervos.org/tree/develop/examples/sudt-script/contracts/sudt/tests/src/tests.rs) for reference. -By writing tests like `test_transfer_sudt`, we can ensure that our sudt script behaves correctly under various scenarios, helping to catch any issues before deployment. +By writing tests like `test_transfer_sudt`, we can ensure that our sUDT Script functions correctly under various scenarios, helping to identity any issues before deployment. --- @@ -370,7 +371,7 @@ By following this tutorial so far, you have mastered how to write a simple UDT S Here's a quick recap: - Use `offckb` and `ckb-script-templates` to init a Script project -- Use `ckb_std` to leverage CKB syscalls `Source::GroupIuput`/`Source::GroupOutput` for performing relevant cells iteration. +- Use `ckb_std` to leverage CKB syscalls `Source::GroupIuput`/`Source::GroupOutput` for performing relevant Cell iteration. - Write unit tests to make sure the UDT Script works as expected. ## Additional Resources