{"content":{"title":"Move on Sui  中级演进","body":"## PTB (Programmable Transaction Block)\r\n\r\n- 在Sui网络上，可编程事务块（PTB）允许用户指定一系列操作（事务）作为单个事务发送到网络\r\n- 这些操作按顺序执行，并且是原子性的 - 如果其中任何一个操作失败，整个PTB都会失败，并且所有的更改都会自动回滚\r\n- **PTB 可以调用 Move模块 中编写的任何 `public` 、`public entry` 和 `entry` (private) 函数**\r\n- 后续会有更加详细的介绍\r\n\r\n## Programmable函数(Function)\r\n\r\n- `public` function\r\n    - 公共函数可以被事务调用, 也可以被其他 Move 代码(模块)调用\r\n    \r\n    ```rust\r\n        public fun fun_name(){}\r\n    ```\r\n    \r\n- `private` function\r\n    - 私有函数只能在同一模块中被调用\r\n    \r\n    ```rust\r\n        fun fun_name(){}\r\n    ```\r\n    \r\n- `public(friend)` function\r\n    - `public(friend)` 函数只能被同一包(package)中的模块(module)调用\r\n    - 要用到 `public(friend)`函数, 需要使用 use 引入\r\n    - 在定义 `public(friend)`函数的 module 中, 需要显式声明 `friend [address]::[module_name]`\r\n    \r\n    ```rust\r\n    module 0x123::my_other_module {\r\n        use 0x123::my_module;\r\n    \r\n        public fun do_it(x: u64): bool {\r\n            my_module::friend_only_equal(x)\r\n        }\r\n    }\r\n    \r\n    module 0x123::my_module {\r\n        friend 0x123::my_other_module;\r\n    \r\n        public(friend) fun friend_only_equal(x: u64): bool {\r\n            x == 1000\r\n        }\r\n    }\r\n    ```\r\n    \r\n- `Entry` function\r\n    - entry 主要是为了控制和管理交易的入口点\r\n    - `public entry` function: 与 `public` function 实际没有区别\r\n    - `entry` function(private): 可以直接从**事务**中调用而不能在其他 module 中调用(自身所在的module 还是可以调用的, 但是不推荐)\r\n    - 我们希望用户必须明确地在事务中调用此功能，而不希望其他模块代表用户 clip_ticket\r\n        \r\n        ```rust\r\n        entry fun clip_ticket(ticket: Ticket) {\r\n            let Ticket {\r\n                  id,\r\n                  expiration_time: _,\r\n              } = ticket;\r\n              object::delete(id);\r\n        }\r\n        ```\r\n        \r\n\r\n## Struct abilities (结构体能力)\r\n\r\n- key\r\n    - 在 Sui 中, `key` 能力表示一个结构体是一个 `Object 类型`, 并且要求结构体的第一个字段是 `id: UID` (链上的唯一地址), Sui 的字节码验证器会保证 UID 不会重复\r\n        \r\n        ```rust\r\n        struct AdminCap has key {\r\n            id: UID,\r\n            num_frens: u64,\r\n        }\r\n        ```\r\n        \r\n- copy\r\n    - `copy` 能力允许一个结构体被“复制”，从而创建一个具有完全相同额字段值的结构体实例\r\n        \r\n        ```rust\r\n        struct CopyableStruct has copy {\r\n            value: u64,\r\n        }\r\n        \r\n        fun copy(original: CopyableStruct) {\r\n            let copy = original;\r\n            original.value = 1;\r\n            copy.value = 2;\r\n            // We now have two CopyableStructs with two different values.\r\n        }\r\n        ```\r\n        \r\n- store\r\n    - `store` 能力允许一个结构体成为其他结构体的一部分\r\n        \r\n        ```rust\r\n            public struct NestedStruct has store {\r\n                value: u64,\r\n                doubleNested: DoubleNestedStruct,\r\n            }\r\n        \r\n            public struct DoubleNestedStruct has store {\r\n                value: u64,\r\n            }\r\n            \r\n            public struct Container has key {\r\n                id: UID,\r\n                nested: NestedStruct,\r\n            }\r\n        ```\r\n        \r\n- drop\r\n    - `drop` 能力允许在函数结束时隐式销毁结构体，而无需进行“析构”操作\r\n        \r\n        ```rust\r\n        struct DroppableStruct has drop {\r\n            value: u64,\r\n        }\r\n        \r\n        fun copy() {\r\n            let droppable = DroppableStruct { value: 1 };\r\n            // At the end of this function, droppable would be destroyed.\r\n            // We don't need to explicitly destruct:\r\n            // let DroppableStruct { value: _ } = droppable;\r\n        }\r\n        ```\r\n        \r\n- Note: **只有当结构体的所有字段具有相同的能力时, 结构体才具体相关的能力**\r\n\r\n## Object wrapping (对象封装)\r\n\r\n- 当我们常见一个对象, 对象内部又包含一个对象, 那么我们在新建实例的时候, 如果初始化呢?\r\n- 例如在 `Box` 对象中包含了一个 `Thing` 对象:\r\n    - 方法 1: 在当前 module 中创建一个新的函数 - create，它创建一个 `Thing` 对象并将其返回，而不像mint函数那样立即将其传递给发送者\r\n    - 方法 2: 首先 mint `Thing` 对象, mint 之后在当前 Transaction 无法检索到 mint 的 `Thing` 对象, 需要在后续的 Transaction 中显示的传递\r\n        \r\n        ```rust\r\n        struct Box has key {\r\n            id: UID,\r\n            thing: Thing,\r\n        }\r\n        \r\n        struct Thing has key, store {\r\n            id: UID,\r\n        }\r\n        \r\n        public fun wrap(thing: Thing, ctx: &mut TxContext) {\r\n            let box = Box { id: object::new(ctx), thing };\r\n            transfer::transfer(box, tx_context::sender(ctx));\r\n        }\r\n        ```\r\n        \r\n\r\n## 不可变对象(Immutable object)\r\n\r\n- 上次提到的 `Object` 都是 `owned object` : 是私有对象，只有拥有它们的用户才能读取和修改(所有权)\r\n- 之前还提到过共享对象 `shared object` : 可以被任何用户读取和修改\r\n- 不可变对象 `Immutable object`: 不可变对象与共享对象几乎相同。任何用户都可以将它们作为其交易的一部分。然而，共享对象可以作为可变引用包含，因此可以被任何人修改。不可变对象在被“冻结”后永远不会改变\r\n    \r\n    ```rust\r\n    struct ColorObject has key {\r\n        id: UID,\r\n        red: u8,\r\n        green: u8,\r\n        blue: u8,\r\n    }\r\n    \r\n    public entry fun freeze_owned_object(object: ColorObject) {\r\n        transfer::freeze_object(object)\r\n    }\r\n    \r\n    public entry fun create_immutable(red: u8, green: u8, blue: u8, ctx: &mut TxContext) {\r\n        let color_object = ColorObject {\r\n            id: object::new(ctx),\r\n            red,\r\n            green,\r\n            blue,\r\n         };\r\n        transfer::freeze_object(color_object);\r\n    }\r\n    ```\r\n    \r\n    - `create_immutable` 创建一个对象并立即将其冻结，使其成为不可变的\r\n    - `transfer` 的其他 freeze 函数:\r\n        - `freeze_owned_object`:  提供一个现有的 `owned object` 并使其成为`不可变对象`\r\n    - Note: 如果在 `shared object` 上调用 `transfer::freeze_object` ，将会出错!!!\r\n    - 不可变对象可以随时通过不可变引用(&) 包含\r\n        \r\n        ```rust\r\n        public fun read_immutable(color: &ColorObject): (u8, u8, u8) {\r\n            (color.red, color.green, color.blue)\r\n        }\r\n        ```\r\n        \r\n\r\n## Transfer Policy\r\n\r\n- Public transfer: `transfer::public_transfer`\r\n    - 具有 `store` 能力的 `Object` 可以通过 `transfer::public_transfer` 在定义这个 Object 的module 之外进行 transfer\r\n        - 复习: 既然是一个 Object, 那一定有 key\r\n- Private transfer:  `transfer::transfer`\r\n    - 没有 `store` 能力的对象**只能在定义它的模块内部进行传输**\r\n\r\n## Wrapping object 与 Non-Object struct\r\n\r\n- Wrapping object\r\n    - 使用对象封装可以创建复杂的对象层次结构，其中每个对象都是独立的，并具有其唯一的标识符\r\n    - 这种方式很强大,  但不总是必要\r\n- Non-Object struct\r\n    - **只具有 store 能力**的 `struct` 就是 `Non-Object struct`\r\n    - 这种方法通常在不打算将嵌套的结构类型转换为对象时才有用。这可以将一个长的对象结构分解为更小的组\r\n        - long object\r\n            \r\n            ```rust\r\n            struct LongObject has key {\r\n                id: UID,\r\n                field_1: u64,\r\n                field_2: u64,\r\n                field_3: u64,\r\n                field_4: u64,\r\n                field_5: u64,\r\n                field_6: u64,\r\n                field_7: u64,\r\n                field_8: u64,\r\n            }\r\n            ```\r\n            \r\n        - big object\r\n            \r\n            ```rust\r\n            struct BigObject has key {\r\n                id: UID,\r\n                field_group_1: FieldGroup1,\r\n                field_group_2: FieldGroup2,\r\n                field_group_3: FieldGroup3,\r\n            }\r\n            \r\n            struct FieldGroup1 has store {\r\n                field_1: u64,\r\n                field_2: u64,\r\n                field_3: u64,\r\n            }\r\n            \r\n            struct FieldGroup2 has store {\r\n                field_4: u64,\r\n                field_5: u64,\r\n                field_6: u64,\r\n            }\r\n            \r\n            struct FieldGroup3 has store {\r\n                field_7: u64,\r\n                field_8: u64,\r\n            \r\n            }\r\n            ```\r\n            \r\n\r\n## Objects & 并行执行 & 共识\r\n\r\n- **Owned对象:** 只有一个所有者可以控制和操作的对象。这种类型的对象对于大多数应用场景都是首选，因为它们易于管理，且与特定用户或合约直接关联。\r\n- **Shared对象:** 用于表示多个用户之间共享的状态。这类对象可以被多个方同时访问和修改，因此在需要跨多用户共享数据时使用。然而，由于Shared对象的修改需要全网共识来处理潜在的冲突，这使得操作 `Shared对象` 的**成本**比操作 `Owned` 或 `Immutable` 对象要高。\r\n- **Immutable对象:** 是指一旦创建就不能被修改的对象。对于不需要改变的共享状态，优先使用Immutable对象，因为它们比Shared对象更高效。Immutable对象不需要处理修改冲突的问题，因此它们在性能和成本方面都比Shared对象更有优势\r\n- 最佳实践\r\n    - 如果数据永远不会改变，合约的所有共享状态都应该是`不可变的对象`\r\n    - 可更新的共享状态的`共享对象` (效率最低)\r\n    - `owned object` 用于其他一切事物\r\n\r\n## System Objects\r\n\r\n### One-time Witness Object (见证对象)\r\n\r\n- 当部署一个模块时，任何定义的`init`函数将被自动调用。这个`init`函数可以接收一个见证对象，这是一个特殊的系统对象，仅在模块第一次部署时创建一次\r\n    \r\n    ```rust\r\n    module 0x123::my_module {\r\n        struct MY_MODULE has drop {}\r\n        \r\n        fun init(witness: MY_MODULE) {\r\n            // 使用见证对象执行操作。\r\n        }\r\n    }\r\n    ```\r\n    \r\n- 为了在`init`函数中接收见证对象，需要声明一个与模块名称相同（全大写，保留下划线）的结构体，并且这个结构体必须具有`drop`能力。然后，在定义`init`函数时，可以将该类型的见证对象作为第一个参数\r\n- 目前有两种用途\r\n    - **声明发布者对象（Publisher Object）**：发布者对象是证明部署者已经部署了该对象的证明\r\n        \r\n        ```rust\r\n        fun init(witness: MY_MODULE, ctx: &mut TxContext) {\r\n            assert!(types::is_one_time_witness(&witness), ENotOneTimeWitness);\r\n            let publisher_object = package::claim(witness, ctx);\r\n            // 使用或存储发布者对象...\r\n        }\r\n        \r\n        ```\r\n        \r\n    - **证明正在初始化流程中调用其他模块的函数**：当需要作为项目初始化的一部分与多个不同模块进行一系列操作时，这通常很有用\r\n        \r\n        ```rust\r\n        module 0x123::module_b {\r\n        // 在 module_b 的 init fun 中传入 A 的 witness, 作用是保证初始化顺序可控\r\n            fun init(module_a_witness: MODULE_A, ctx: &mut TxContext) {\r\n                assert!(types::is_one_time_witness(&module_a_witness), ENotOneTimeWitness);\r\n            }\r\n        }\r\n        \r\n        ```\r\n        \r\n\r\n### Publisher Object (发布者对象)\r\n\r\n- 用途\r\n    - **创建显示对象（Display Objects）**： 下面会提及\r\n    - **在Sui的Kiosk（NFT标准）中设置转移策略**：这将在NFT中介绍\r\n\r\n### Display Object\r\n\r\n- `Display<T>` : 指示如何为特定类型的 object **显示字段**的 object, 下面是函数原型:\r\n    \r\n    ```rust\r\n    struct Display<phantom T: key> has key, store {\r\n        id: UID,\r\n        /// Contains fields for display. Currently supported\r\n        /// fields are: name, link, image and description.\r\n        fields: VecMap<String, String>,\r\n        /// Version that can only be updated manually by the Publisher.\r\n        version: u16\r\n    }\r\n    ```\r\n    \r\n- 意味着开发者可以为存储在区块链上的对象定义如何在用户界面（比如`web UI`）中显示它们的字段\r\n- 如果创建 display 对象\r\n    1. **获取Publisher对象引用**：这个对象证明了调用者有权为特定模块（**`MyObject`**所在的模块）创建Display对象。Publisher对象是在模块部署时通过特定的初始化流程创建的\r\n    2. **调用`display::new`函数**：创建一个新的Display对象。这个过程需要**`Publisher`**对象的引用和 transaction 上下文（`ctx`）\r\n    3. **设置显示规则**：通过调用`display::add_multiple`函数，你可以为`MyObject`的特定字段添加格式化规则。这个函数接受两个 vector，一个是要显示的字段列表，另一个是对应的格式化字符串\r\n    4. **更新版本并广播**：调用`display::update_version`函数来确认对Display对象所做的更改，并触发一个事件，这个事件被Sui网络节点捕捉到后，可以让这些节点识别到新的或更新的Display对象\r\n- 一旦Display对象被创建并设置好，每当通过节点API获取对象时，它的显示属性也会根据指定的格式计算出来，并与对象的其他字段一起返回\r\n- 代码:\r\n    \r\n    ```rust\r\n    module 0x123::my_module {\r\n        struct MyObject has key {\r\n            id: UID,\r\n            num_value: u64,\r\n            string_value: String,\r\n        }\r\n        \r\n        public fun create_display_object(publisher: &Publisher, ctx: &mut TxContext) {\r\n            let display_object = display::new<MyObject>(&publisher, ctx);\r\n            display::add_multiple(\r\n                &mut display,\r\n                vector[\r\n                    utf8(b\"num_value\"),\r\n                    utf8(b\"string_value\"),\r\n                ],\r\n                vector[\r\n                    utf8(b\"Value: {num_value}\"),\r\n                    utf8(b\"Description: {string_value}\"),\r\n                ],\r\n            );\r\n            display::update_version(&mut display);\r\n        }\r\n    }\r\n    ```\r\n    \r\n\r\n### Clock\r\n\r\n- 允许用户获取链上记录的当前时\r\n- Sui区块链提供了一个特殊的系统对象，名为`Clock`，允许用户获取链上记录的当前时间。这个功能在智能合约编程中非常有用，尤其是在需要对事件进行时间戳记录或者基于时间生成伪随机数的场景中。\r\n    1. **获取当前时间**：\r\n        - `Clock`对象允许通过`clock::timestamp_ms`函数获取当前的时间戳。\r\n        - 返回的时间戳以毫秒为单位，即1秒等于1000毫秒。\r\n    2. **时间戳的常见用途**包括但不限于：\r\n        - **记录保持**：用时间戳记录事件发生的具体时刻。例如，可以创建一个结构体`TimeEvent`，包含时间戳字段`timestamp_ms`，并在特定操作时发出事件，将时间戳记录下来。\r\n            \r\n            ```rust\r\n            struct TimeEvent has copy, drop {\r\n                timestamp_ms: u64,\r\n            }\r\n            \r\n            public entry fun log_event(clock: &Clock) {\r\n                event::emit(TimeEvent { timestamp_ms: clock::timestamp_ms(clock) });\r\n            }\r\n            \r\n            ```\r\n            \r\n    3. **生成伪随机数**：利用时间戳作为种子来生成伪随机数。这种方法虽然方便，但技术上容易受到验证者操纵，因为验证者可以在很小的误差范围内设置时间戳。\r\n        \r\n        ```rust\r\n        entry fun flip_coin(clock: &Clock): u64 {\r\n            let timestamp_ms = clock::timestamp_ms(clock);\r\n            // 0是正面，1是反面\r\n            timestamp_ms % 2\r\n        }\r\n        \r\n        ```\r\n        \r\n    4. **安全事项**：\r\n        - 当使用时间戳来生成伪随机数时，需要注意这种方法的安全性。在一些场景下，由于验证者对时间戳有一定的控制能力，可能会影响到伪随机数的公正性\r\n    5. **使用`Clock`对象的条件**：\r\n        - 要访问**`Clock`**对象，需要在合约函数中将其作为参数传入\r\n\r\n### TxContext\r\n\r\n- 提供了关于当前事务的上下文信息\r\n- **需要小心安全问题**\r\n- 主要用途\r\n    1. **创建新对象的ID**：\r\n        - 使用`object::new(ctx)`来创建一个新的对象ID。这个ID是唯一的，确保了对象在全局的唯一性\r\n    2. **获取发送者地址**：\r\n        - 通过`tx_context::sender(ctx)`获取当前事务的发送者地址。这可以用来确定是谁发起了当前的事务\r\n- **`TxContext`的其他功能**\r\n    - **事务哈希**：**`digest`**函数返回当前事务的哈希值，可以用于日志记录或跟踪\r\n    - **当前纪元和时间戳**：`epoch`和`epoch_timestamp_ms`函数分别返回当前的纪元号和对应的时间戳，有助于实现基于时间的逻辑\r\n    - **生成新对象地址**：`fresh_object_address`使用与`object::new`相同的底层函数来生成新对象的地址，这对于创建新对象时指定特定的地址可能很有用\r\n\r\n## Struct data access\r\n\r\n- 具有存储能力的对象可以转移到使用 `transfer::public_transfer` 定义的同一模块之外\r\n- 没有存储能力的对象只能在定义它的同一模块中使用 `transfer::transfer` 进行传输\r\n\r\n## Summary\r\n\r\n1. func: `public / private / public entry/ private entry`\r\n2. PTB\r\n3. Struct abilities: `key, store, copy, drop`\r\n4. object: object wrapping / 不可变对象 /系统对象 / 可转让性\r\n## 加入组织, 一起交流/学习!\r\n- [Sui 中文开发群(TG)](https://t.me/move_cn)\r\n- 企鹅群: 79489587"},"author":{"user":"https://learnblockchain.cn/people/18883","address":"0x1d791545aeee89011c20a32c5be31623c604cb1b"},"history":"bafkreiaqafdtdud5iuehxxuztbmtiyyxds6ooglsd66ntac7tlxaqo7aky","timestamp":1710875896,"version":1}