1 个不稳定版本

0.0.0 2022 年 10 月 14 日

#38#parity-wasm

Apache-2.0

2KB

ink!

Polkadot 的 ink! 用于编写智能合约

linux codecov coveralls loc stack-exchange

squink,ink! 的吉祥物ink! 是一个用于在基于 Substrate 框架的区块链上编写智能合约的 Rust eDSL。ink! 合约被编译为 WebAssembly。


初学者指南  •   ink! 文档门户  •   开发者文档


更多相关链接

目录

玩耍

开始的最佳方式是查看我们的文档中的入门页面。

如果您想本地设置,可以使用我们的substrate-contracts-node进行快速入门。这是一个简单的Substrate区块链,其中包括智能合约功能的Substrate模块——contracts组件(更多内容请参阅如何工作)。

我们还在Rococo上有一个名为"Contracts"的实时测试网。Rococo是基于Substrate的平行链,支持ink!智能合约。有关使用此测试网的进一步说明,请参阅我们的文档

可以使用Contracts UI将您的合约实例化到链上并与它交互。

用法

编译智能合约的前提是已安装Rust和Cargo。以下是安装指南

我们还建议安装cargo-contract。这是一个CLI工具,可以帮助设置和管理使用ink!编写的WebAssembly智能合约。

cargo install cargo-contract --force

使用--force确保您已更新到最新的cargo-contract版本。

要初始化一个新的ink!项目,可以使用

cargo contract new flipper

这将为您的工作目录中创建一个名为flipper的文件夹。该文件夹包含一个模板Cargo.toml和一个lib.rs,这两个文件都包含了使用ink!所需的构建块。

lib.rs中包含我们的hello world合约——Flipper,我们将在下一节中解释。

要构建合约,只需在flipper文件夹中执行此命令

cargo contract build

结果,您将在合约的target文件夹中获得一个flipper.wasm文件、一个flipper.json文件和一个<contract-name>.contract文件。该.contract文件将Wasm和元数据合并到一个文件中,并在实例化合约时需要使用。

你好,世界! — 翻转器

Flipper合约是一个简单的合约,仅包含一个bool值。

它提供以下方法

  • 将它的值从true翻转至false(反之亦然)
  • 并返回当前状态。

以下是使用ink!编写的代码。

#[ink::contract]
mod flipper {
    /// The storage of the flipper contract.
    #[ink(storage)]
    pub struct Flipper {
        /// The single `bool` value.
        value: bool,
    }

    impl Flipper {
        /// Instantiates a new Flipper contract and initializes
        /// `value` to `init_value`.
        #[ink(constructor)]
        pub fn new(init_value: bool) -> Self {
            Self {
                value: init_value,
            }
        }

        /// Flips `value` from `true` to `false` or vice versa.
        #[ink(message)]
        pub fn flip(&mut self) {
            self.value = !self.value;
        }

        /// Returns the current state of `value`.
        #[ink(message)]
        pub fn get(&self) -> bool {
            self.value
        }
    }

    /// Simply execute `cargo test` in order to test your contract
    /// using the below unit tests.
    #[cfg(test)]
    mod tests {
        use super::*;

        #[ink::test]
        fn it_works() {
            let mut flipper = Flipper::new(false);
            assert_eq!(flipper.get(), false);
            flipper.flip();
            assert_eq!(flipper.get(), true);
        }
    }
}

我们示例文件夹中的flipper/src/lib.rs文件包含此代码。运行cargo contract build来构建您的第一个ink!智能合约。

示例

examples仓库中,您可以找到许多使用ink!编写的示例。

其中一些最有趣的示例

  • basic_contract_ref - 实现跨合约调用。
  • trait-erc20 - 定义一个用于Erc20合约的特性和实现它。
  • erc721 - Erc721 NFT代币的一个示例实现。
  • dns - 一个简单的DomainNameService智能合约。
  • …还有更多,只需翻翻文件夹吧 🙃。

要构建单个示例,请导航到示例的根目录并运行

cargo contract build

现在你应该在合约的 target 文件夹中有一个 <name>.contract 文件。

有关如何将此文件上传到链的信息,请参阅动手玩一玩部分或我们的智能合约研讨会

工作原理

  • Substrate的模块化实体运行时聚合框架(FRAME)包含一个模块,该模块实现了一个API,用于智能合约需要的典型函数(存储、查询账户信息等)。这个模块被称为contracts 模块,
  • contracts 模块要求智能合约以Wasm blob的形式上传到区块链。
  • ink! 是一种面向contracts 暴露的API的智能合约语言。因此,ink! 合约被编译为Wasm。
  • 当执行cargo contract build 时,将创建一个额外的文件 <contract-name>.json。它包含有关合约提供的方法等信息。

ink! 宏和属性概述

入口点

在带有#[ink::contract] 注解的模块中,这些属性可用:

属性 适用范围 描述
#[ink(storage)] struct 定义上。 定义ink!存储结构。每个合约中只能有一个ink!存储定义。
#[ink(message)] 适用于方法。 将ink!存储结构中的方法标记为消息,使其可通过API调用合约。
#[ink(constructor)] 适用于方法。 将ink!存储结构中的方法标记为构造函数,使其可通过API实例化合约。
#[ink(event)] struct 定义上。 定义ink!事件。合约可以定义多个此类ink!事件。
#[ink(anonymous)] 适用于ink!事件。 告诉ink!代码生成器将ink!事件视为匿名,在发射时省略事件签名作为主题。类似于Solidity中的匿名事件。
#[ink(signature_topic= _)] 适用于ink!事件。 指定事件的自定义签名主题,允许手动指定共享事件定义。
#[ink(topic)] 适用于ink!事件字段。 告诉ink!代码生成器为给定字段提供主题哈希。每个ink!事件只能有有限数量的此类主题字段。类似于Solidity中的索引事件参数。
#[ink(payable)] 适用于ink!消息。 允许在ink!消息调用中接收值。ink!构造函数隐式为可支付。
#[ink(selector=S:u32)] 适用于ink!消息和ink!构造函数。 指定被标记实体的具体调度选择器。这允许合约作者精确控制其API的选择器,使得在不破坏的情况下重命名API成为可能。
#[ink(selector= _)] 适用于ink!消息。 指定在没有任何ink!消息与选择器匹配时调用的回退消息。
#[ink(namespace=N:string)] 适用于ink!特性实现块。 更改特性实现中所有ink!消息和ink!构造函数的结果选择器。允许区分具有重叠消息或构造函数名称的特性实现。请谨慎使用并仔细考虑!
#[ink(impl)] 适用于ink!实现块。 通知ink!代码生成器,某些实现块即使不包含ink!消息或ink!构造函数,也应获得访问ink!内建的权限。

请参见此处了解更详细的描述,以及有关#[ink::contract]宏的详细信息。

特质定义

使用#[ink::trait_definition]来定义您自己的特质定义,然后ink!智能合约可以实现这些定义。例如,请参见examples/trait-erc20合约,了解如何使用它或文档以获取详细信息。

链下测试

#[ink::test]过程宏实现了链下测试。例如,请参见examples/erc20合约,了解如何使用它或文档以获取详细信息。

开发者文档

我们有一个非常全面的文档门户,但如果您正在寻找 crate 级别的文档本身,则这些是相关链接。

文档 描述
ink ink!公开的语言特性。请参见此处了解您可以在#[ink::contract]中使用属性的全部详细信息。
ink_storage ink!中可用的数据结构。
ink_env 与智能合约Wasm执行器交互的低级接口。同时包含链下测试API
ink_prelude 无_std和std通用的API,用于访问alloc crate类型。

社区徽章

常规设计

Built with ink!

[![Built with ink!](https://raw.githubusercontent.com/use-ink/ink/master/.images/badge.svg)](https://github.com/use-ink/ink)

平面设计

Built with ink!

[![Built with ink!](https://raw.githubusercontent.com/use-ink/ink/master/.images/badge_flat.svg)](https://github.com/use-ink/ink)

贡献

访问我们的贡献指南以获取更多信息。

使用scripts/check-*目录下提供的脚本,以便在workspaces或所有示例上运行检查。请在将工作推送到PR之前执行此操作。

许可证

此存储库中的所有代码均受Apache License 2.0许可。

无运行时依赖