Skip to content

Commit

Permalink
[docs] Update move-on-rooch relative docs (#1874)
Browse files Browse the repository at this point in the history
  • Loading branch information
jolestar authored Jun 12, 2024
1 parent 37dd109 commit 94bbf95
Show file tree
Hide file tree
Showing 14 changed files with 183 additions and 125 deletions.
1 change: 1 addition & 0 deletions docs/website/pages/build/rooch-framework/_meta.en-US.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,6 @@
"cryptographic-primitives": "Cryptographic primitives",
"timestamp": "Timestamp",
"private-generics": "Private generics",
"data-struct": "Data Struct",
"unit-test": "Unit test"
}
1 change: 1 addition & 0 deletions docs/website/pages/build/rooch-framework/_meta.zh-CN.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,6 @@
"cryptographic-primitives": "密码原语",
"timestamp": "时间戳",
"private-generics": "私有泛型",
"data-struct": "数据结构体",
"unit-test": "单元测试"
}
44 changes: 44 additions & 0 deletions docs/website/pages/build/rooch-framework/data-struct.en-US.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Data Struct

import { Callout, FileTree } from 'nextra/components'

`#[data_struct]` is a struct annotation used to mark a struct as a pure data struct, allowing it to be directly deserialized within a contract. This feature is designed to facilitate developers in retrieving data from external data sources.

## Example

```move
module my_project::my_module {
#[data_struct]
struct MyData has copy, drop {
value: u64,
name: vector<u8>,
}
}
```

With this annotation, developers can directly deserialize the `MyData` struct within a contract:

```move
let data: MyData = moveos_std::bcs::from_bytes(bytes);
```

The `moveos_std::bcs::from_bytes` function also uses the `#[data_struct(T)]` annotation to ensure that `T` must be a `#[data_struct]` type.

```move
module moveos_std::bcs {
#[data_struct(T)]
/// Function to deserialize a type T.
/// The `data_struct` annotation ensures that `T` must be a `#[data_struct]` type.
public fun from_bytes<T>(bytes: vector<u8>): T;
}
```

## How It Works

The `#[data_struct]` annotation is implemented based on the Move verifier, which checks the struct definition at compile time to ensure it meets the `data_struct` requirements. Additionally, the contract is re-verified during deployment.

## Data Struct Specification

<Callout>
TODO: This part of the document needs improvement.
</Callout>
44 changes: 44 additions & 0 deletions docs/website/pages/build/rooch-framework/data-struct.zh-CN.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# 数据结构体

import { Callout, FileTree } from 'nextra/components'

`#[data_struct]` 是一个结构体注解,用于标记结构体为纯数据结构体,使其可以在合约中直接反序列化。这个特性旨在方便开发者从外部数据源获取数据。

## 示例

```move
module my_project::my_module {
#[data_struct]
struct MyData has copy, drop {
value: u64,
name: vector<u8>,
}
}
```

这样,开发者就可以在合约中直接反序列化 `MyData` 结构体:

```move
let data: MyData = moveos_std::bcs::from_bytes(bytes);
```

`moveos_std::bcs::from_bytes` 函数也使用了 `#[data_struct(T)]` 注解,确保 `T` 必须是一个 `#[data_struct]` 类型。

```move
module moveos_std::bcs {
#[data_struct(T)]
/// 反序列化类型 T 的函数。
/// `data_struct` 注解确保 `T` 必须是一个 `#[data_struct]` 类型。
public fun from_bytes<T>(bytes: vector<u8>): T;
}
```

## 工作原理

`#[data_struct]` 基于 Move 的验证器实现,在编译时检查结构体的定义是否符合 `data_struct` 的要求。同时,在合约部署时也会进行再次验证。

## 数据结构体规范

<Callout>
TODO 这部分文档需要改进
</Callout>
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,20 @@ The `#[private_generics(T)]` function annotation ensures that functions annotate

This annotation is particularly useful for developing foundational contract libraries. It ensures that functions with this annotation cannot be called arbitrarily by users and can only be called through higher-level contract functions.

Let's take `AccountStorage` as an example. We want to store a user's resources within their storage space, but at the same time, we want to restrict a contract to only operate on the resource types it defines and prevent it from operating on resource types defined by other contracts. This is where the `#[private_generics(T)]` annotation comes into play.
Let's take `Account` as an example. We want to store a user's resources within their storage space, but at the same time, we want to restrict a contract to only operate on the resource types it defines and prevent it from operating on resource types defined by other contracts. This is where the `#[private_generics(T)]` annotation comes into play.

```move
module moveos_std::account_storage{
module moveos_std::account{
#[private_generics(T)]
public fun borrow_resource<T: key>(ctx: &Context, account: address): &T;
/// Borrow a mut resource from the account's storage
/// This function equates to `borrow_global_mut<T>(address)` instruction in Move
public fun borrow_mut_resource<T: key>(account: address): &mut T;
}
```

In the above example, we define a `borrow_resource` function with a private generic `T` which can only be used within the module where `T` is defined. Other modules cannot use this function.
In the above example, we define a `borrow_mut_resource` function with a private generic `T` which can only be used within the module where `T` is defined. Other modules cannot use this function.

### How it works
## How it works

`#[private_generics(T)]` is implemented based on Move's verifier, which checks the validity of function calls at compile-time. If an incorrect call is detected, it will result in an error. Additionally, the validity of function calls is checked during contract deployment.

Expand All @@ -28,8 +30,7 @@ TODO: This part of the document needs improvement.
### References

1. The `#[private_generics(T)]` annotation is used in the following modules, which can serve as references:
- [moveos_std::account_storage](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/account_storage.move)
- [moveos_std::storage_context](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/storage_context.move)
- [moveos_std::account](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/account.move)
- [moveos_std::signer](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/signer.move)
- [rooch_framework::coin](https://github.com/rooch-network/rooch/blob/main/frameworks/rooch-framework/sources/coin.move)
2. [Understanding Private Generics Functions in one article](../../blog/read-private-generics-in-one-article)
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,20 @@ import { Callout, FileTree } from 'nextra/components'

这个注解对开发基础合约库非常有用,因为它可以保证添加了该注解的函数不能被用户随意调用,只能通过上层合约封装的函数进行调用。

`AccountStorage` 为例,我们希望将用户的`资源(Resource)`都保存在用户的存储空间内,但又要求某个合约只能操作自己定义的资源类型,不能操作其他合约定义的资源类型,这时候就可以使用 `#[private_generics(T)]` 注解来实现。
`Account` 为例,我们希望将用户的`资源(Resource)`都保存在用户的存储空间内,但又要求某个合约只能操作自己定义的资源类型,不能操作其他合约定义的资源类型,这时候就可以使用 `#[private_generics(T)]` 注解来实现。

```move
module moveos_std::account_storage{
module moveos_std::account{
#[private_generics(T)]
public fun borrow_resource<T: key>(ctx: &StorageContext, account: address): &T;
/// Borrow a mut resource from the account's storage
/// This function equates to `borrow_global_mut<T>(address)` instruction in Move
public fun borrow_mut_resource<T: key>(account: address): &mut T;
}
```

在上面的例子中,我们定义了一个 `borrow_resource` 函数,它的泛型 `T` 是私有的,只能在 `T` 所在的模块内使用,其他模块无法使用该函数。
在上面的例子中,我们定义了一个 `borrow_mut_resource` 函数,它的泛型 `T` 是私有的,只能在 `T` 所在的模块内使用,其他模块无法使用该函数。

### 它是如何工作的
## 工作原理

`#[private_generics(T)]` 是基于 Move 的 verifier 实现的,它会在编译时检查函数调用的合法性,如果发现错误的调用,就会报错。同时,合约部署的时候也会检查函数调用的合法性。

Expand All @@ -28,8 +30,7 @@ module moveos_std::account_storage{
### 参考链接

1. 以下模块中使用了 `#[private_generics(T)]` 注解,可以作为参考:
- [moveos_std::account_storage](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/account_storage.move)
- [moveos_std::storage_context](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/storage_context.move)
- [moveos_std::account](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/account.move)
- [moveos_std::signer](https://github.com/rooch-network/rooch/blob/main/frameworks/moveos-stdlib/sources/signer.move)
- [rooch_framework::coin](https://github.com/rooch-network/rooch/blob/main/frameworks/rooch-framework/sources/coin.move)
2. [一文读懂私有泛型函数](../../blog/read-private-generics-in-one-article)
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# Rooch's built-in library

Rooch currently has three built-in standard libraries, namely `MoveStdlib`, `MoveosStdlib` and `RoochFramework`.
Rooch currently has four built-in standard libraries, namely `MoveStdlib`, `MoveosStdlib`, `RoochFramework` and `BitcoinMove`.

The addresses of the three libraries in Move are:
The addresses of the four libraries in Move are:

- `MoveStdlib`: `0x1`
- `MoveosStdlib`: `0x2`
- `RoochFramework`: `0x3`
- `BitcoinMove``0x4`

## Documentation link

- [MoveStdlib](https://github.com/rooch-network/rooch/tree/main/frameworks/move-stdlib/doc)
- [MoveosStdlib](https://github.com/rooch-network/rooch/tree/main/frameworks/moveos-stdlib/doc)
- [RoochFramework](https://github.com/rooch-network/rooch/tree/main/frameworks/rooch-framework/doc)
- [BitcoinMove](https://github.com/rooch-network/rooch/tree/main/frameworks/bitcoin-move/doc)
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# Rooch 的内置库

Rooch 当前内置了三个标准库,分别是 `MoveStdlib``MoveosStdlib``RoochFramework`
Rooch 当前内置了四个标准库,分别是 `MoveStdlib``MoveosStdlib``RoochFramework``BitcoinMove`

三个库在 Move 中的地址分别是:
四个库在 Move 中的地址分别是:

- `MoveStdlib``0x1`
- `MoveosStdlib``0x2`
- `RoochFramework``0x3`
- `BitcoinMove``0x4`

## 文档链接

- [MoveStdlib](https://github.com/rooch-network/rooch/tree/main/frameworks/move-stdlib/doc)
- [MoveosStdlib](https://github.com/rooch-network/rooch/tree/main/frameworks/moveos-stdlib/doc)
- [RoochFramework](https://github.com/rooch-network/rooch/tree/main/frameworks/rooch-framework/doc)
- [BitcoinMove](https://github.com/rooch-network/rooch/tree/main/frameworks/bitcoin-move/doc)
Loading

0 comments on commit 94bbf95

Please sign in to comment.