如何使用本书

欢迎体验《EasyRooch》！这本书是为零基础学者设计的Rooch开发指南，无论你是刚接触区块链的新手，还是想快速上手Rooch开发的编程爱好者，这里都能帮你从零开始，逐步掌握Rooch的开发技能。

什么是Rooch？

Rooch是一个致力于构建比特币生态系统应用层的Layer 2区块链项目。它通过原生方法扩展比特币的功能，让你可以用比特币资产（如BTC、Ordinals、BRC20）开发去中心化应用（DApp），并保持比特币级别的安全性。

  • 如果你是用户：你的所有比特币资产可以在Rooch支持的应用程序中直接使用，无需通过托管桥。
  • 如果你是开发者：Rooch提供了一个易于编程的MoveVM环境，让你通过智能合约无缝访问比特币的完整状态，打造与比特币互操作的应用。
  • 如果你是社区成员：Rooch确保你的资产是比特币L1的原生资产，随时可以无需许可地回到比特币主网。

本书将带你走进Rooch的世界，从基础到实践，解锁它的强大潜力。

本书的目标

Rooch的核心开发工具是Move语言，一个简单又安全的区块链编程语言。本书的目标是通过通俗易懂的讲解和丰富的实践示例，帮助你：

  • 掌握Move语言的基础知识。
  • 学会使用Rooch框架开发比特币相关的智能合约。
  • 熟悉Rooch核心库的功能，并将其应用到实际项目中。

无论你是想开发一个比特币投票应用、NFT市场，还是探索DeFi项目，这本书都将为你提供从零开始的坚实基础。

本书的结构

本书分为以下几个部分，循序渐进地引导你学习Rooch开发：

  1. Move基础

    • 从Move语言的基本语法开始，逐步深入到对象、动态字段、集合等进阶主题。
    • 为零基础读者设计，帮助你打好语言基础。

  2. Rooch开发入门

    • 介绍如何搭建Rooch开发环境并编写第一个比特币相关的智能合约。
    • 通过简单示例，快速带你进入Rooch开发。

  3. Rooch进阶开发

    • 探索Rooch的高级功能，如状态绑定和CSV资产跃迁，以及复杂项目的开发技巧。
    • 包括性能优化和安全最佳实践。

  4. 实战项目

    • 通过三个实用项目（投票应用、NFT市场、DeFi借贷平台），将理论转化为实践能力。
    • 每个项目都有详细步骤，适合动手操作。

  5. Rooch核心库参考

    • 提供Rooch框架核心库的“字典式”讲解，例如账户管理（moveos_std::account）、存储上下文（moveos_std::storage_context）等。
    • 方便你在开发时快速查询和使用。

  6. Rooch核心库错误代码速查

    • 列出Rooch核心库中常见的错误代码及其含义，帮助你快速排查开发中的问题。
    • 适合作为调试时的参考工具。

  7. 附录

    • 解答常见问题并提供额外资源，帮助你深入学习Rooch和比特币生态。

如何阅读本书

如果你是零基础读者

  • 建议：从头开始，按顺序阅读，尤其是“Move基础”和“Rooch开发入门”部分。
  • 方法：边读边动手，跟着示例代码操作。书中提供了大量代码片段，建议你在本地运行和修改，加深理解。
  • 时间：每天1-2小时，预计2-3个月完成全书并上手Rooch开发。

如果你有编程经验

  • 建议：快速浏览“Move基础”，重点关注“Rooch开发入门”和“实战项目”。
  • 方法：直接尝试项目章节，并在需要时查阅“Rooch核心库参考”和“Rooch错误代码速查”。
  • 时间：1-2周即可掌握Rooch开发核心技能。

如果你是中高级开发者

  • 建议：跳到“Rooch进阶开发”、“核心库参考”和“错误代码速查”，快速了解Rooch与比特币的互操作性。
  • 方法：将核心库应用到自己的项目，参考“设计模式”和“性能与安全”优化代码。

前置知识

本书尽量保持零基础友好，但以下知识会让学习更顺利：

  • 基础编程概念：了解变量、函数、循环等（任何语言都可以）。
  • 比特币基础：知道什么是UTXO、Ordinals或BRC20（不要求深入）。
  • 如果你完全没接触过编程或比特币，别担心！我们会从最简单的概念开始讲解。

工具准备

开始学习前，请准备以下工具：

  • 电脑：Windows、Mac或Linux系统。
  • 开发环境：按照“搭建开发环境”章节配置Move和Rooch CLI（后续详细说明）。
  • 文本编辑器：推荐VS Code，配合Move插件使用。

学习建议

  1. 动手实践

    • 不要只看代码，一定要运行和修改它们。实践是掌握Rooch的关键。
    • 尝试用Rooch访问比特币状态，例如读取一个UTXO。

  2. 记录笔记

    • 记下关键点（如状态绑定的用法）或问题，方便复习。

  3. 加入社区

    • Rooch和比特币有活跃的开发者社区，遇到问题可以在Rooch论坛或GitHub提问。

  4. 逐步挑战

    • 完成实战项目后，试着开发自己的比特币应用，例如一个简单的BRC20代币管理工具。

Rooch的独特优势

Rooch不仅是一个开发框架，它还为比特币生态带来了创新：

  • 比特币完整状态：你可以直接在智能合约中访问和解释比特币的UTXO、Ordinals等。
  • 无需许可的资产跃迁：通过CSV资产（如Bitseed协议），你的比特币资产可以自由在Rooch应用和L1之间移动。
  • 高性能：Rooch支持并行执行，峰值TPS可达10万。

这些特性将在后续章节详细展开，让你真正感受到Rooch的强大。

下一步

准备好了吗？请翻到下一章《Move基础》，从“Move快速入门”开始你的Rooch开发之旅，探索如何用Move语言构建比特币生态的应用吧！

Rooch开发入门

Move快速入门

欢迎来到Move语言的世界！Move是Rooch开发的核心编程语言，专为区块链设计，简单、安全又强大。本章将带你快速了解Move的基本概念，并通过一个简单示例让你动手试一试。不用担心复杂细节，我们会从最基础的部分开始！

什么是Move？

Move是一种为区块链智能合约设计的编程语言，由Facebook的Libra项目（现为Diem）开发。它有以下特点：

  • 安全性：通过资源管理防止资产重复花费。
  • 简单性：语法类似Rust，容易上手。
  • 灵活性：支持Rooch等区块链框架的开发。

在Rooch中，Move用来编写智能合约，帮助你创建去中心化应用（DApp）。本章将让你快速体验它的基本用法。

Move的核心概念

1. 模块（Module）

  • 模块是Move代码的基本组织单位，类似一个“文件”或“类”。
  • 每个模块可以定义数据和函数。

2. 资源（Resource）

  • Move用“资源”表示数字资产，比如代币或NFT。
  • 资源不能被复制或丢弃，只能被转移，确保安全性。

3. 函数（Function）

  • 函数定义了操作逻辑，例如创建资源或转移资产。
  • 有“公开函数”和“入口函数”，我们会用到后者。

第一个Move程序

让我们动手写一个简单的计数器程序！这个程序会在Rooch上存储一个数字，每次调用时增加1。

代码示例

注意：以下代码中的中文注释仅为教学查看，实际Move代码不支持中文注释，请在运行时移除这些注释。

module MyCounter::Counter {
    use std::signer;
    use moveos_std::account;

    // 定义一个资源，包含一个计数器值
    struct Counter has key {
        value: u64
    }

    // 初始化计数器（入口函数）
    public entry fun init_counter(account: &signer) {
        // 创建计数器，初始值为0
        let counter = Counter { value: 0 };
        // 将计数器存储到调用者的账户下
        account::move_resource_to(account, counter);
    }

    // 增加计数器（入口函数）
    public entry fun increment(account: &signer) {
        // 获取调用者的计数器
        let counter = account::borrow_mut_resource<Counter>(signer::address_of(account));
        // 值加1
        counter.value = counter.value + 1;
    }
}

搭建开发环境

Binary install

建议使用二进制安装方法，因为它简单快捷。通过使用预编译的二进制文件，您可以在系统上快速设置 Rooch，而无需从源代码构建，从而确保与 Ubuntu 版本的兼容性并最大限度地缩短设置时间。

Ubuntu 24.04

Download

Download the latest Rooch binary for Ubuntu 24.04:

wget https://github.com/rooch-network/rooch/releases/latest/download/rooch-ubuntu-latest.zip

Decompress

unzip rooch-ubuntu-latest.zip

Install

sudo cd rooch-artifacts/ && cp rooch /usr/local/bin

Ubuntu 22.04

Download

Download the latest Rooch binary for Ubuntu 22.04:

wget https://github.com/rooch-network/rooch/releases/latest/download/rooch-ubuntu-22.04.zip

Decompress

unzip rooch-ubuntu-22.04.zip

Install

sudo cd rooch-artifacts/ && cp rooch /usr/local/bin

Compile and install

Ubuntu

Install dependencies

sudo apt install git curl cmake make gcc lld pkg-config libssl-dev libclang-dev libsqlite3-dev g++ protobuf-compiler

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone source code

git clone https://github.com/rooch-network/rooch.git

Compile and install Rooch

cd rooch && cargo build && cp target/debug/rooch ~/.cargo/bin/

Binary install

建议使用二进制安装方法，因为它简单快捷。通过使用预编译的二进制文件，您可以在系统上快速设置 Rooch，而无需从源代码构建，从而确保与 MacOS 版本的兼容性并最大限度地缩短设置时间。

MacOS Arm

Download

wget https://github.com/rooch-network/rooch/releases/latest/download/rooch-macos-latest.zip

Decompress

unzip rooch-macos-latest.zip

Install

sudo cp rooch /usr/local/bin

Compile and install

macOS

Homebrew

Use the following command to install Homebrew:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install dependencies

brew install curl cmake libpq git

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone source code

git clone https://github.com/rooch-network/rooch.git

Compile and install Rooch

cd rooch && cargo build && cp target/debug/rooch ~/.cargo/bin/

领取Rgas

RGas 主要用于支付 Rooch 网络上的交易费用。用户在执行交易时，需要消耗一定数量的 RGas 来支付计算和存储成本。

详细介绍：https://rooch.network/zh-CN/learn/core-concepts/rgas

步骤一：

访问url：https://test-portal.rooch.network/faucet

image-20250318161156667

步骤二：

连接钱包，可以选择支持的三个钱包之一进行连接。

image-20250318161339181

步骤三：

连接钱包后点击Claim: 1RGas 进行领取即可。

image-20250318161415293

Rooch Cli常见命令

以下是一些常用的 rooch 子命令及其简单用法示例，帮助你快速上手：

运行 rooch 命令后，你会看到以下帮助信息，列出了所有可用子命令及其简要描述：

Usage: rooch <COMMAND>

Commands:
  version        Retrieves events based on their event handle
  account        Tool for interacting with accounts
  bitcoin        
  bitseed        Tool for interacting with bitseed protocol
  init           Tool for init with rooch
  move           
  server         Start Rooch network
  task           Tool for run some task
  state          Get states by accessPath
  object         
  dynamic-field  Dynamic Field Commands
  resource       Get account resource by tag
  transaction    Tool for interacting with transaction [aliases: tx]
  event          Tool for interacting with event
  abi            
  env            Interface for managing multiple environments
  session-key    
  rpc            
  statedb        Statedb Commands
  indexer        Indexer Commands
  genesis        Statedb Commands
  upgrade        Tool for interacting with system upgrade
  db             DB Commands
  util           
  faucet         Faucet commands
  oracle         Oracle commands
  da             DA Commands
  help           Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

rooch init

用于初始化 Rooch 的本地配置，例如生成默认配置文件。

rooch init

Creating client config file ["/root/.rooch/rooch_config/rooch.yaml"].
Enter a password to encrypt the keys. Press enter to leave it an empty password: 
Generated new keypair for address [rooch1s5y679r9j8m02szf0fr6ffcrhdasvhhzka4v59fdqc6ndp7xj3wsu7pvny]
Secret Recovery Phrase : [mountain weapon whip denial tray damp weekend coast picnic toddler endorse call]
Rooch client config file generated at /root/.rooch/rooch_config/rooch.yaml

rooch env

  • 查看已有环境 (list)

下列是当前默认的一些环境配置，默认应用的是test。

rooch env list
╭───────────┬─────────────────────────────────┬───────────────┬────────────╮
│ Env Alias │ RPC URL                         │ Websocket URL │ Active Env │
├───────────┼─────────────────────────────────┼───────────────┼────────────┤
│ local     │ http://127.0.0.1:6767           │ Null          │            │
│ dev       │ https://dev-seed.rooch.network  │ Null          │ True       │
│ test      │ https://test-seed.rooch.network │ Null          │            │
│ main      │ https://main-seed.rooch.network │ Null          │            │
╰───────────┴─────────────────────────────────┴───────────────┴────────────╯
  • 切换环境 (switch)
rooch env switch
error: the following required arguments were not provided:
  --alias <ALIAS>

Usage: rooch env switch --alias <ALIAS>

For more information, try '--help'.

# 这里可以使用别名来进行切换
rooch env switch --alias dev
The active environment was successfully switched to `dev`
  • 添加环境 (add)

添加别名以及rpc的url即可。

rooch env add --alias test-rooch --rpc https://test-seed.rooch.network
Environment `test-rooch was successfully added
  • 移除环境 (remove)
rooch env remove
error: the following required arguments were not provided:
  --env <ENV>

Usage: rooch env remove --env <ENV>

For more information, try '--help'.

#这里也是根据别名即可移除

rooch env remove --env test-rooch
Environment `test-rooch` was successfully removed

rooch account

  • 创建新账户 (create)

会基于init时创建钱包的助记词继续创建新的账户。

rooch account create

Generated new keypair for address with key pair type [rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh]
Secret Recovery Phrase : [mountain weapon whip denial tray damp weekend coast picnic toddler endorse call]
  • 查看账户 (list)

查看Cli 中的所有账户，Active 为True时代表你当前使用的是哪个账户。

rooch account list
╭──────────────────┬───────────────────────────────────────────────────────────────────────────┬────────────╮
│ Field            │ Value                                                                     │ Active     │
├──────────────────┼───────────────────────────────────────────────────────────────────────────┼────────────┤
│ Address          │ rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh          │ False      │
│ Hex Address      │ 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c        │            │
│ Bitcoin Address  │ bcrt1puq36h99xwjxgq005p8kx97uvnmu3x7hzarm7n3hxsxxh0f8jfn3sqdjvyl          │            │
│ Public Key       │ 0x028912a48902bb1ff0f66366c40d0e1d2904603964d561399363334f4f03239d34      │            │
│ Nostr Public Key │ npub13yf2fzgzhv0lpanrvmzq6rsa9yzxqwty64snnymrxd857qern56qmef756           │            │
│ ──────────────── │ ───────────────────────────────────────────────────────────────────────── │ ────────── │
│ Address          │ rooch1s5y679r9j8m02szf0fr6ffcrhdasvhhzka4v59fdqc6ndp7xj3wsu7pvny          │ True       │
│ Hex Address      │ 0x8509af146591f6f540497a47a4a703bb7b065ee2b76aca152d06353687c6945d        │            │
│ Bitcoin Address  │ bcrt1pg6er56jr394flxy73l7lr229ch5xme4f63zd0yqt77zng9kt7tsqm2x34d          │            │
│ Public Key       │ 0x03e35e180b0242b341f988f9b7f7bc8df6db6ba91f11c6f387bfc9f6e579573624      │            │
│ Nostr Public Key │ npub1ud0pszczg2e5r7vglxml00yd7mdkh2glz8r08pale8mw272hxcjqgzy0gc           │            │
│ ──────────────── │ ───────────────────────────────────────────────────────────────────────── │ ────────── │
╰──────────────────┴───────────────────────────────────────────────────────────────────────────┴────────────╯
  • 查看账户余额 (balance)

可以查看当前账户的余额。

rooch account balance
╭───────────┬────────┬──────────┬─────────╮
│ Coin Type │ Symbol │ Decimals │ Balance │
├───────────┼────────┼──────────┼─────────┤
│ Bitcoin   │ BTC    │ 8        │ 0       │
╰───────────┴────────┴──────────┴─────────╯
  • 切换账户 (switch)

用来切换当前使用的账户。

rooch account switch
error: the following required arguments were not provided:
  --address <ADDRESS>

Usage: rooch account switch --address <ADDRESS>

For more information, try '--help'.

#可以根据list中查询出来的address来进行切换

rooch account switch --address rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh
The active account was successfully switched to `rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh`
  • 导出账户 (export)

会导出当前使用账户的助记词。

rooch account export
Export succeeded with the mnemonic phrase [mountain weapon whip denial tray damp weekend coast picnic toddler endorse call]
  • 导入账户 (import)

这里需要传入钱包账户的hex格式的私钥进行导入。

rooch account import --secretkey 1d6701355158a08a2ee734f47b0951138a813ecf9f6c3341ddfa1cec30e97018
Import succeeded with address [rooch1s5y679r9j8m02szf0fr6ffcrhdasvhhzka4v59fdqc6ndp7xj3wsu7pvny] and the secret key

rooch server

这一小节将给大家介绍如何使用 Rooch CLI 来运行本地开发环境。

当前版本，我们分别提供了 rooch server start 和 rooch server clean 命令来启动 Rooch 本地服务和清理服务器存储。

  • rooch server start

当我们编写完 Rooch Move 合约项目，我们需要启动 Rooch 开发环境来部署和测试合约。

rooch server start
Rooch DAO address: rooch1u2gret96h9nvcm4mkka2anygup6ch4cf4am6ljhd8ss5x3alp53stuzvrt(0xe2903cacbab966cc6ebbb5baaecc88e0758bd709af77afcaed3c214347bf0d23)
Rooch DAO Bitcoin address: bc1p9z34rs94s80pq5jv7tch3u4nk6vh60gh6w45x0ysad605nwwvd6qydc7vp
2025-03-17T09:27:32.569865Z  INFO raw_store: Metrics task cancelled for store instance
2025-03-17T09:27:33.043639Z  INFO rooch_rpc_server: The latest Root object state root: 0xc206f7dec61e6f7e797a2ff0dcc97ded13e4b48d6451f8fbae7066b9643e671f, size: 60
2025-03-17T09:27:33.046335Z  INFO rooch_rpc_server: RPC Server sequencer address: rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh(0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c)
2025-03-17T09:27:33.046518Z  INFO rooch_sequencer::actor::sequencer: Load latest sequencer order 0
2025-03-17T09:27:33.046534Z  INFO rooch_sequencer::actor::sequencer: Load latest sequencer accumulator info AccumulatorInfo { accumulator_root: 0x6281998bf4491035269064ece002ff1a344fa4850c8b05d87008ddec3be9a826, frozen_subtree_roots: [0x6281998bf4491035269064ece002ff1a344fa4850c8b05d87008ddec3be9a826], num_leaves: 1, num_nodes: 1 }
2025-03-17T09:27:33.064451Z  INFO rooch_rpc_server: DA meta issues: 0, fixed: 0
2025-03-17T09:27:33.065036Z  INFO rooch_rpc_server: RPC Server proposer address: rooch1yeyk0vdj9k4xp95ppyywtuqdk8sy3rm3lc9qv0ys2lp08jl7suxqh8aryh(0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c)
2025-03-17T09:27:33.090864Z  INFO rooch_rpc_server: acl=Const("*")
2025-03-17T09:27:33.094787Z  INFO rooch_rpc_server: JSON-RPC HTTP Server start listening 0.0.0.0:6767
2025-03-17T09:27:33.094845Z  INFO rooch_rpc_server: Available JSON-RPC methods : ["btc_broadcastTX", "rooch_getObjectStates", "rooch_repairIndexer", "rooch_queryObjectStates", "rooch_getBalance", "rooch_sendRawTransaction", "rooch_dryRunRawTransaction", "rooch_getTransactionsByHash", "rooch_executeRawTransaction", "rooch_getEventsByEventHandle", "rooch_queryEvents", "rooch_queryTransactions", "rooch_executeViewFunction", "rooch_listFieldStates", "rooch_getBalances", "rooch_getModuleABI", "rooch_listStates", "rooch_getTransactionsByOrder", "rooch_syncStates", "rooch_getChainID", "rooch_getFieldStates", "rooch_status", "rooch_checkChangeSets", "btc_queryUTXOs", "btc_queryInscriptions", "rpc.discover", "rooch_queryFields", "rooch_getStates"]
2025-03-17T09:27:33.099285Z  INFO rooch_rpc_server: rate limiting storage size: 0
The active env was successfully switched to `local`

  • 本地测试网信息

    名称: local
    ChainID: 4
    RPC: http://localhost:6767

  • rooch server clean

如果有遇到服务数据冲突的问题，首先执行清除命令，再继续启动服务：

rooch server clean
Are you sure to clean the rooch data dir: "/root/.rooch/local" ?(Y/n)

Rooch storage "/root/.rooch/local" successfully cleaned

因为 Rooch 正处于快速开发迭代的过程，在部署合约时，可能会遇到兼容性问题，此时可以通过 clean 命令来清理旧的数据。

Bitcoin本地开发环境

Linux 搭建

  • docker 搭建

可参考官方文章进行搭建：
https://github.com/rooch-network/rooch/blob/main/scripts/bitcoin/README.md

MacOS 搭建

  • 非docker 搭建

1、下载Bitcoin core

url: https://bitcoin.org/en/bitcoin-core/

安装后会进行区块同步

image-20250317170649297

然后在配置里面启用RPC服务器

image-20250317171521228

然后再编辑配置文件，内容如下：

[regtest]
rpcallowip=0.0.0.0/0
rpcbind=0.0.0.0
rpcport=18443

# 全局设置（适用于所有网络）
txindex=1
fallbackfee=0.00001

# ZeroMQ 配置（适用于所有网络）
zmqpubrawblock=tcp://0.0.0.0:28332
zmqpubrawtx=tcp://0.0.0.0:28333


# 如果您希望更快速地产生块，可设置自动生成
blockmintime=1  # 每秒生成一个块（仅测试用）

# 数据同步块间隔（可选）
minrelaytxfee=0.00001
# RPC 用户认证
rpcauth=roochuser:925300af2deda1996d8ff66f2a69dc84$681057d8bdccae2d119411befa9a5f949eff770933fc377816348024d25a2402

保存后进行自动操作创建，创建shell脚本方便后续使用。

/Applications/Bitcoin-Qt.app/Contents/MacOS/Bitcoin-Qt -regtest

image-20250317171741175

然后保存后启动，可以看到带有regtest

image-20250317171911461

然后启动rooch server

rooch server start -n local \
    --btc-rpc-url http://127.0.0.1:18443 \
    --btc-rpc-username roochuser \
    --btc-rpc-password roochpass \
    --btc-sync-block-interval 1

效果如下：

image-20250317172254422

如果遇到启动失败的情况：

rooch server start -n local \
    --btc-rpc-url http://127.0.0.1:18443 \
    --btc-rpc-username roochuser \
    --btc-rpc-password roochpass \
    --btc-sync-block-interval 1
Rooch DAO address: rooch1zs7qtkdc0eh0nxscue4957fc26hva2p9euhaxcc35fkuz45807usyh6yuy(0x143c05d9b87e6ef99a18e66a5a793856aecea825cf2fd36311a26dc156877fb9)
Rooch DAO Bitcoin address: bc1pf9r8g03dtq8z2qd8vcg7xnkmtlg6pljrqe4072lm0un2lfzgxzgstg2p5g
2025-03-17T09:21:28.242791Z  INFO raw_store: Metrics task cancelled for store instance
2025-03-17T09:21:28.362761Z  INFO raw_store: Metrics task cancelled for store instance
2025-03-17T09:21:28.394338Z ERROR rooch_rpc_server: GenesisVersionMismatch { from_store: GenesisInfo { genesis_package_hash: 0x51994afb886d0e08681c36322d00d307d8183f2b43127894839b98c7da55caa1}, from_binary: GenesisInfo { genesis_package_hash: 0x1548ecd2e5bb55293ebaede860c1ea09cbfe925649e7fa7dce6015a917476d1d} }, please clean your data dir. `rooch server clean -n local`

则需要运行rooch server clean -n local 进行清除本地缓存。

  • docker 搭建

可参考官方文章进行搭建：
https://github.com/rooch-network/rooch/blob/main/scripts/bitcoin/README.md

rooch move

rooch move 是与 Move 语言开发相关的工具集，提供编译、测试和发布等功能。以下是其帮助信息和常用子命令简介：

  • 新建项目 (new)
# 使用rooch move new <项目名称>即可创建
$rooch move new hello
Success

#命令执行后在当前目录下会创建和项目名称相同的目录
$ls
test

#test目录结构如下
.
├── Move.toml
└── sources
    └── hello.move
  • 编译项目 (build)

编辑在new命令中创建的文件 hello.move

module hello::hello {
    use moveos_std::account;
    use std::string;

    struct HelloMessage has key {
        text: string::String
    }

    public entry fun say_hello(owner: &signer) {
        let hello = HelloMessage { text: string::utf8(b"Hello Rooch!") };
        account::move_resource_to(owner, hello);
    }
}

然后可以在hello目录下执行编译的命令，成功后结果如下：

$rooch move build
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
INCLUDING DEPENDENCY MoveStdlib
INCLUDING DEPENDENCY MoveosStdlib
INCLUDING DEPENDENCY RoochFramework
BUILDING hello
Exported package to ./build/hello/package.rpd
Success
  • 测试项目 (test)

该命令用来测试合约中的功能是否可以正常使用。

编辑hello.move文件:

module hello::hello {
    use moveos_std::account;
    use std::string;

    struct HelloMessage has key {
        text: string::String
    }

    public entry fun say_hello(owner: &signer) {
        let hello = HelloMessage { text: string::utf8(b"Hello Rooch!") };
        account::move_resource_to(owner, hello);
    }

    #[test(sender=@0x42)]
    fun test_stake(sender: &signer){
        say_hello(sender);
    }
}

在执行的时候可能会遇到这种情况：

rooch move test
Error: Unable to resolve packages for package 'hello'
While resolving dependency 'MoveosStdlib' in package 'hello'
Failed to fetch to latest Git state for package 'MoveosStdlib', to skip set --skip-fetch-latest-git-deps | Exit status: exit status: 128

这时候需要加上--skip-fetch-latest-git-deps，成功执行后如下：

rooch move test
INCLUDING DEPENDENCY MoveStdlib
INCLUDING DEPENDENCY MoveosStdlib
INCLUDING DEPENDENCY RoochFramework
BUILDING hello
Running Move unit tests
[ PASS    ] 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::test_stake
Test result: OK. Total tests: 1; passed: 1; failed: 0
  • 部署项目 (publish)

通过build和test之后初步确定合约没有错误后可以进行部署。

如果是首次部署，钱包内没有rgas 会出现下列的报错内容：

rooch move publish
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
INCLUDING DEPENDENCY MoveStdlib
INCLUDING DEPENDENCY MoveosStdlib
INCLUDING DEPENDENCY RoochFramework
BUILDING hello
Publish modules to address: 264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c
Transaction error: ErrorObject { code: ServerError(2), message: "status ABORTED of type Execution with sub status 1004", data: None }

需要领取rgas之后在进行部署，领取rgas 参考领取Rgas。

成功部署后如下：

rooch move publish
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
UPDATING GIT DEPENDENCY https://github.com/rooch-network/rooch.git
INCLUDING DEPENDENCY MoveStdlib
INCLUDING DEPENDENCY MoveosStdlib
INCLUDING DEPENDENCY RoochFramework
BUILDING hello
Publish modules to address: 264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c
Execution info:
    status: Executed
    gas used: 1318976
    tx hash: 0x29c9a8eaae6f0430d10930522aab28f7f7e479389d22990d12d9a0280e2d9e82
    state root: 0xd9a69167baf27f6a563d4b7fd9073d88496da8632461fe62c08418ee58a87bc2
    event root: 0xee6300870946ec81db8654af859ff685671ac173af63e4a69885769de5db05f4

New modules:
    0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello

Updated modules:
    None

New objects:
    objectId: 0x14481947570f6c2f50d190f9a13bf549ab2f0c9debc41296cd4d506002379659264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c
    type    : 0x2::module_store::Package

    objectId: 0x14481947570f6c2f50d190f9a13bf549ab2f0c9debc41296cd4d506002379659264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c2db8971282e9227073eceff88867c864237fa06e529892c5addf335b5e84f13a
    type    : 0x2::object::DynamicField<0x1::string::String, 0x2::move_module::MoveModule>

    objectId: 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c
    type    : 0x2::account::Account

    objectId: 0x2ec24e80179f353555d1012f896a708dcf1f441ffb4131413af0cb245510e7216bcf17da2ce4bf1980589f3e8faad8862c8f4723372230cd5112949f869ca885
    type    : 0x2::object::DynamicField<address, 0x3::bitcoin_address::BitcoinAddress>

    objectId: 0x82327808cb5077c8a2f9520286cc90dd748753135ff2b3119df0b5a4bfe0a2b8
    type    : 0x2::module_store::UpgradeCap
            
Modified objects:
    objectId: 0x14481947570f6c2f50d190f9a13bf549ab2f0c9debc41296cd4d506002379659
    type    : 0x2::module_store::ModuleStore

    objectId: 0x29344e813f7dec57c632a72c07c5c0ec653a094d524bfc221f6ab3a32d5de9c5
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0x2ec24e80179f353555d1012f896a708dcf1f441ffb4131413af0cb245510e721
    type    : 0x3::address_mapping::RoochToBitcoinAddressMapping

    objectId: 0x4e5ceb9b30a672308137d1d636497c805340a7d29a927adb150dd1354f924bf0
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0x6b271d90caa1dcce1222822a5ded0bf4f3eef88b721dc2303a59f073463255a8
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0xb6fc47ae8cbd3d22dcb2f6b1c17a0e5ce926ab0efb799fab28e31c5acbe752d1
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

Removed objects:
    None

如果遇到有如下的提示：

Failed to fetch to latest Git state for package 'MoveosStdlib', to skip set --skip-fetch-latest-git-deps | Exit status: exit status: 128

加上--skip-fetch-latest-git-deps 再执行即可。

  • 调用合约 (run)

当成功部署合约之后就可以通过run来调用已部署的合约，在publish中已经部署了合约，这里直接调用。

rooch move run --function 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::say_hello
Execution info:
    status: Executed
    gas used: 327056
    tx hash: 0xa833f1dbd225b822948598fe8547c0a21d8cf3c115ca6c71cb8c328668d8ce50
    state root: 0x5f29c924812b508a4db0c0dfe78712421bde717edef41e8c6ad42290681dee88
    event root: 0x345d02121ff1b018fc7979492280f0d06a1bfd4d6b033553d87d1830fe8a271a

New objects:
    objectId: 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870cb09a8140a9f24d9ea947c12605da3bc3de312307d29776b4f791a617e45e6d84
    type    : 0x2::object::DynamicField<0x1::string::String, 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage>

    objectId: 0x5900af94221897cbb995f35c2aeb1ee24a56174a321e6956036b33accc5e8deb
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0xd66d0c2e9b47f75f2a6dca80584208333c3327cf89326b905d3850b9970f13f36bcf17da2ce4bf1980589f3e8faad8862c8f4723372230cd5112949f869ca885
    type    : 0x2::object::DynamicField<address, 0x2::object::Object<0x3::coin_store::CoinStore<0x3::gas_coin::RGas>>>
            
Modified objects:
    objectId: 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c
    type    : 0x2::account::Account

    objectId: 0x29344e813f7dec57c632a72c07c5c0ec653a094d524bfc221f6ab3a32d5de9c5
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0x4e5ceb9b30a672308137d1d636497c805340a7d29a927adb150dd1354f924bf0
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0x6b271d90caa1dcce1222822a5ded0bf4f3eef88b721dc2303a59f073463255a8
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0xb6fc47ae8cbd3d22dcb2f6b1c17a0e5ce926ab0efb799fab28e31c5acbe752d1
    type    : 0x3::coin_store::CoinStore<0x3::gas_coin::RGas>

    objectId: 0xd66d0c2e9b47f75f2a6dca80584208333c3327cf89326b905d3850b9970f13f3
    type    : 0x3::transaction_fee::TransactionFeePool

Removed objects:
    None

Events:
    event handle id: 0x18e4e7d4ead4c9a9be261bbe4c140e06c12a6e9bd7cad46a9f44caa4acc4174c
    event seq      : 5552143
    event type     : 0x3::coin_store::WithdrawEvent

    event handle id: 0xb853393e53406be49dfd6325e65de25eae00c348cbe0b2cec8ea56513fa2c26a
    event seq      : 11128202
    event type     : 0x3::coin_store::DepositEvent

    event handle id: 0x18e4e7d4ead4c9a9be261bbe4c140e06c12a6e9bd7cad46a9f44caa4acc4174c
    event seq      : 5552144
    event type     : 0x3::coin_store::WithdrawEvent

    event handle id: 0xb853393e53406be49dfd6325e65de25eae00c348cbe0b2cec8ea56513fa2c26a
    event seq      : 11128203
    event type     : 0x3::coin_store::DepositEvent

    event handle id: 0x3797fc63218944e37225cf62545e1bfa77cbd404214017e4ce5effa6e2e62e53
    event seq      : 1195
    event type     : 0x3::coin_store::CreateEvent

    event handle id: 0xb853393e53406be49dfd6325e65de25eae00c348cbe0b2cec8ea56513fa2c26a
    event seq      : 11128204
    event type     : 0x3::coin_store::DepositEvent

    event handle id: 0xb853393e53406be49dfd6325e65de25eae00c348cbe0b2cec8ea56513fa2c26a
    event seq      : 11128205
    event type     : 0x3::coin_store::DepositEvent

    event handle id: 0xb853393e53406be49dfd6325e65de25eae00c348cbe0b2cec8ea56513fa2c26a
    event seq      : 11128206
    event type     : 0x3::coin_store::DepositEvent

这里面还有一些传入参数方法,可以通过help进行查看。

rooch move run --help
Run a Move function

Usage: rooch move run [OPTIONS] --function <FUNCTION>

Options:
      --function <FUNCTION>
          Function name as `<ADDRESS>::<MODULE_ID>::<FUNCTION_NAME>` Example: `0x42::message::set_message`, `rooch_framework::empty::empty`

      --type-args <TYPE_ARGS>
          TypeTag arguments separated by spaces.
          
          Example: `0x1::M::T1 0x1::M::T2 rooch_framework::empty::Empty`

      --args <ARGS>
          If there are multiple parameters, multiple `--args` modifications are required.
          
          Example: rooch move run --function 0x3::MODULE::FUNCTION --args u64:15 --args @0x42
          
          Supported types [u8, u16, u32, u64, u128, u256, bool, object_id, string, address, vector<inner_type>]
          
          Example: `address:0x1 bool:true u8:0 u256:1234 'vector<u32>:a,b,c,d'` address and uint can be written in short form like `@0x1 1u8 4123u256`.

      --password <PASSWORD>
          The key store password

      --config-dir <CONFIG_DIR>
          rooch config path

      --sender <SENDER>
          Sender account address
          
          [default: default]

      --sequence-number <SEQUENCE_NUMBER>
          Custom account's sequence number

      --max-gas-amount <MAX_GAS_AMOUNT>
          Custom the transaction's gas limit. [default: 1_000_000_000] [alias: "gas-limit"]

      --authenticator <AUTHENTICATOR>
          Custom the transaction's authenticator format: `auth_validator_id:payload`, auth validator id is u64, payload is hex string example: 123:0x2abc

      --session-key <SESSION_KEY>
          Sign the transaction via session key This option conflicts with `authenticator`

      --json
          Return command outputs in json format

      --gas-profile
          Run the gas profiler and output html report

      --dry-run
          Run the DryRun for this transaction

  -h, --help
          Print help (see a summary with '-h')

rooch state

rooch state 是一个查询工具，用于通过“访问路径”（access-path）获取 Rooch 区块链上的状态数据（states）。这些状态数据可以是链上的对象（object）、资源（resource）、模块（module）或表（table）的内容。

rooch state --help
Get states by accessPath

Usage: rooch state [OPTIONS] --access-path <ACCESS_PATH>

Options:
  -a, --access-path <ACCESS_PATH>  /object/$object_id1[,$object_id2] /resource/$account_address/$resource_type1[,$resource_type2] /module/$account_address/$module_name1[,$module_name2] /table/$object_id/$key1[,$key2]
      --password <PASSWORD>        The key store password
      --config-dir <CONFIG_DIR>    rooch config path
      --show-display               Render and return display fields
  -h, --help                       Print help

以在rooch move中的hello合约为例：

objectId: 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870cb09a8140a9f24d9ea947c12605da3bc3de312307d29776b4f791a617e45e6d84
    type    : 0x2::object::DynamicField<0x1::string::String, 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage>

调用合约的时候创建了一个HelloMessage ，下面使用rooch state 来进行查询，可以看到其中的内容"text": "Hello Rooch!"：

#使用rooch state --access-path /object/$object_id1[,$object_id2] 
rooch state --access-path /object/0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870cb09a8140a9f24d9ea947c12605da3bc3de312307d29776b4f791a617e45e6d84
[
  {
    "id": "0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870cb09a8140a9f24d9ea947c12605da3bc3de312307d29776b4f791a617e45e6d84",
    "owner": "rooch1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqhxqaen",
    "owner_bitcoin_address": null,
    "flag": 0,
    "state_root": "0x5350415253455f4d45524b4c455f504c414345484f4c4445525f484153480000",
    "size": "0",
    "created_at": "1742296062000",
    "updated_at": "1742296062000",
    "object_type": "0x2::object::DynamicField<0x1::string::String, 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage>",
    "value": "0x573078323634393637623162323264616136303936383130393038653566303064623165303438386637316665306130363363393035376332663363626665383730633a3a68656c6c6f3a3a48656c6c6f4d6573736167650c48656c6c6f20526f6f636821",
    "decoded_value": {
      "abilities": 12,
      "type": "0x2::object::DynamicField<0x1::string::String, 0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage>",
      "value": {
        "name": "0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage",
        "value": {
          "abilities": 8,
          "type": "0x264967b1b22daa6096810908e5f00db1e0488f71fe0a063c9057c2f3cbfe870c::hello::HelloMessage",
          "value": {
            "text": "Hello Rooch!"
          }
        }
      }
    },
    "display_fields": null
  }
]

其他的方式也可以自己进行尝试。

编写第一个Rooch智能合约

调用和测试合约

Rooch进阶开发

实战项目

Rooch SDK参考

Rooch错误代码速查

附录

常见问题解答

资源链接