Rust 智能合约养成日记（10-3）Sputnik DAO::提案介绍

BlockSec
更新于 2022-04-24 17:07
阅读 2222

Sputnik-DAO 作为 NEAR Protocol 所提供的基础设施，正有力地推动着NEAR生态朝向“去中心化”的目标发展🚀。目前该平台已促成了众多的NEAR项目“去中心化”自治社区，同时也提供了完整灵活且高效的社区决策治理解决方案。Sputnikdaov2 🔗是用于 Sputnik-DAO 社区治理投票的智能合约。本期合约代码解读将为大家介绍该合约的核心概念：提案（Proposal），并将在后续的文章中围绕提案介绍相关的DAO社区治理模式（Policy）。

![1.png](https://img.learnblockchain.cn/attachments/2022/04/DzZA9jbd6265109540541.png!/scale/50)

**往期回顾：**

* [Rust智能合约养成日记（1）合约状态数据定义与方法实现](https://learnblockchain.cn/article/3745)
* [Rust智能合约养成日记（2）编写Rust智能合约单元测试](https://learnblockchain.cn/article/3746)
* [Rust智能合约养成日记（3）Rust智能合约部署，函数调用及Explorer的使用](https://learnblockchain.cn/article/3747)
* [Rust智能合约养成日记（4）Rust 智能合约整数溢出](https://learnblockchain.cn/article/3753)
* [Rust智能合约养成日记（5）重入攻击](https://learnblockchain.cn/article/3754)
* [Rust智能合约养成日记（6）拒绝服务攻击](https://learnblockchain.cn/article/3755)
* [Rust智能合约养成日记（7）合约安全之计算精度](https://learnblockchain.cn/article/3756)
* [Rust智能合约养成日记（8）合约安全之权限控制](https://learnblockchain.cn/article/3760)
* [Rust智能合约养成日记（10-1）合约升级](https://mp.weixin.qq.com/s?__biz=MzkwMjIwMjgyMg==&mid=2247484722&idx=1&sn=fa26ec7d847a6b2a07d4de0f514772be&chksm=c0a8519bf7dfd88def3d2d919b3eb4b396df631af00bb687d924cdd76784ba41489bba0421b1&scene=21#wechat_redirect)
* [Rust智能合约养成日记（10-2）Sputnik DAO::Factory合约解读](https://learnblockchain.cn/article/3827)

---

**本期摘要：**

Sputnik-DAO 作为 NEAR Protocol 所提供的基础设施，正有力地推动着NEAR生态朝向“去中心化”的目标发展🚀。

目前该平台已促成了众多的NEAR项目“去中心化”自治社区，同时也提供了完整灵活且高效的社区决策治理解决方案。

`Sputnikdaov2 🔗`是用于 Sputnik-DAO 社区治理投票的智能合约。本期合约代码解读将为大家介绍该合约的核心概念：提案（Proposal），并将在后续的文章中围绕`提案`介绍相关的[DAO社区治理](https://learnblockchain.cn/article/742)模式（Policy）。

> 注：本系列智能合约源代码解析，文章的所有内容均不构成任何数字货币投资理财建议。

---

## 1. 提案发起（Add Proposal）

Sputnik-DAO 社区中的每位成员都有权利就所属项目的治理或管理发表意见或提交提案（Proposal）。随后每个在DAO中持股的社区成员都可以对该提案进行审议和投票。换句话说，Sputnik-DAO 中的每个成员都可以通过对其他成员的提案进行投票或自己发起新的管理提案来影响有关项目未来的走向。

深入合约层面，在 Sputnik-DAO 中，DAO社区成员可调用`sputnikdaov2`合约所提供的`add_proposal()`方法来发起一个新的提案。

```
pub fn add_proposal(&mut self, proposal: ProposalInput) -> u64
```

此时提案者需提供该提案的详细信息（`ProposalInput`）：
![2.png](https://img.learnblockchain.cn/attachments/2022/04/TovaY41D626511274b527.png)

具体含义为：

* 提案的文字描述（`Description`）。此段文字信息将公开展示在 Sputnik-DAO 主页前端，帮助社区成员理解该提案的目的与意义。
* 提案的类型（`kind`）。提案者需依照对项目管理所提的意见类型进行相应的选择（例如：合约关键特权函数的调用需选择`FunctionCall`类型，合约项目资金的转移需选择`Transfer`类型，合约治理权限控制级别`"RolePermission"`的设置/变更需选择`ChangePolicyAddOrUpdateRole`等类型）

以上`ProposalInput`信息将以参数的形式传入`add_proposal()`方法，随后该方法将进一步执行相关的校验与处理，并生成一个带有完整初始化信息的提案（`Proposal`）。最终该提案会与唯一的`proposal_id`相绑定，以<Key, Value>的形式被添加到 Sputnik-DAO 合约全局所维护的 `Contract.proposals`映射中（提案池）。
![3.png](https://img.learnblockchain.cn/attachments/2022/04/hYLlo48t6265114c0bd3d.png)

如下是 Sputnik-DAO 所定义提案所拥有的完整属性信息：
![4.png](https://img.learnblockchain.cn/attachments/2022/04/xdjybvJy62651165c8e1d.png)

在该提案中，`description`与`kind`属性内容将从`proposer`在创建该提案所提供的`ProposalInput`信息中提取。具体为，该合约利用Rust语言 `From trait`实现了`ProposalInput`到`Proposal`的类型转化：
![5.png](https://img.learnblockchain.cn/attachments/2022/04/7jORGL936265118145a39.png)

上述转化过程绑定了更多的提案状态信息：

* 新添加提案中的提案者（`proposer`）属性会被自动赋值为`add_proposal()`方法的调用者，即`env::predecessor_account_id()`，该属性真实且不受用户控制；
* 新添加的提案状态（`status`）被默认初始化为`ProposalStatus::InProgress`，即尚处于投票阶段；
* 新添加提案的发起时间（`submission_time`）被赋值为本区块的时间戳 `env::block_timestamp()`；
* 由于新提案提交时暂无人投票，因此投票状态（`vote_counts`, `votes`）均初始化为空 `HashMap::default()`。

---

需要注意的是：Sputnik-DAO 中存在有提案押金（`proposal_bond`）的概念，该押金将依照具体的 Sputnik-DAO 社区治理模式（Policy）进行管理。

阅读相关代码可知，合约要求提案者在调用`add_proposal()`方法时质押一定数额的 NEAR 代币作为新提案的保证金。
![6.png](https://img.learnblockchain.cn/attachments/2022/04/71NSU6EG626511c018d3f.png)

该笔押金将在提案正常结束（社区投票赞成`ProposalStatus::Approved` | 社区投票反对`ProposalStatus::Rejected`）时通过调用合约的内部函数`internal_return_bonds()`退还给提案人。
![7.png](https://img.learnblockchain.cn/attachments/2022/04/WLmbG1Ql626511de52038.png)

然而，BlockSec 此前在解读该处合约代码时发现：

Sputnik-DAO 在处理提案押金时，**并没有为每一位用户单独地维护历史提案押金数额** 。而当用户发起交易，调用合约方法`add_proposal()`添加新提案时，可能会给该笔交易附加**超过由该 DAO治理策略（Policy）所定义的 `policy.bounty_bond` NEAR代币** 。这将导致**多余的部分押金** ，并不会在后续函数`internal_return_bonds`**执行时返还给提案者** 。

> 在 BlockSec Team 及时与项目方取得联系后，最终该 Issue#158 (https://github.com/near-daos/sputnik-dao-contract/issues/158) 被确认并及时在 PR#160 (https://github.com/near-daos/sputnik-dao-contract/pull/160) 中得到修复🙂。

---

更多 Sputnik-DAO 内部所执行提案相关的校验与处理策略，将在后续推出的《Rust 智能合约养成日记（10-4） Sputnik DAO::社区治理模式剖析》中详细说明。

## 2. 提案状态（Proposal Status）

Sputnik-DAO 中的任何一个标准提案将有可能经历如下多种状态（新的提案状态被初始化为：`InProgress`）
![9.png](https://img.learnblockchain.cn/attachments/2022/04/71LnUqjQ6265120089bd7.png)

具体状态的变化如下图所示：

提案池中的提案状态变化由合约的另一方法`act_proposal()`驱动。
![10.png](https://img.learnblockchain.cn/attachments/2022/04/5vOc5X6k62651224c2100.png)

Sputnik-DAO 成员可调用`act_proposal()`方法对具体的提案（通过id指定）执行如下操作：
![11.png](https://img.learnblockchain.cn/attachments/2022/04/XYeNKs396265124903363.png)

典型的，对于处于`InProgress`状态的提案，DAO社区成员可调用`act_proposal()`执行具体的**投票**操作：

* Action::VoteApprove：表赞成;
* Action::VoteReject：表反对;
* Action::VoteRemove：认为该提案没有实际意义，需移除;

![12.png](https://img.learnblockchain.cn/attachments/2022/04/dfKqbepT6265126cd5f6c.png)

根据上述实现，在内部调用函数`update_votes()`之后，程序会主动调用 `policy.proposal_status()` 进行计票工作。该函数的实现内容如下：
![13.png](https://img.learnblockchain.cn/attachments/2022/04/V347O7CX6265128daaa6b.png)

在该函数中，对于满足投票阈值的提案，提案的状态将进行相应的变更。

变更后：

* 若提案状态为 `Approved`，则该提案将通过调用 `internal_execute_proposal()`被执行；
* 若提案状态为 `Rejected` 或 `Removed`，则该提案将通过调用 `internal_reject_proposal()` 执行后续的收尾操作。

值得一提的是，`Rejected` 与 `Removed` 状态不同之处在于：最终被确定为`Removed` 状态的提案将直接从提案池中移除，（作为惩罚）并不会退还当初所质押的押金给提案者。而对于`Rejected`状态的提案而言，该提案将继续保留在提案池中，并退还相应的押金。

> 更多提案状态将在后续推出的《Rust 智能合约养成日记（10-4） Sputnik DAO::社区治理模式剖析》中进一步说明。

---

## 3. 提案执行（Execute Proposal）

若某一提案在投票结束后状态匹配为 `Approved`，此时合约方法`act_proposal()`内部将继续调用`internal_execute_proposal()`函数执行提案所包含的决策内容。

Sputnik-DAO 所支持的提案类型列举如下（大多类型的提案涉及到了DAO治理模式的配置更新）：

* ProposalKind::ChangeConfig
* ProposalKind::ChangePolicy
* ProposalKind::AddMemberToRole
* ProposalKind::RemoveMemberFromRole
* ProposalKind::FunctionCall
* ProposalKind::UpgradeSelf
* ProposalKind::UpgradeRemote
* ProposalKind::Transfer
* ProposalKind::SetStakingContract
* ProposalKind::AddBounty
* ProposalKind::BountyDone
* ProposalKind::Vote
* ProposalKind::FactoryInfoUpdate
* ProposalKind::ChangePolicyAddOrUpdateRole
* ProposalKind::ChangePolicyRemoveRole
* ProposalKind::ChangePolicyUpdateDefaultVotePolicy
* ProposalKind::ChangePolicyUpdateParameters

以上每一种提案类型在函数`internal_execute_proposal()`中都实现了相应的处理分支。

本小节将深入为大家介绍两种典型的提案类型处理流程：

* ProposalKind::FunctionCall
* ProposalKind::Transfer

### 3.1 合约函数执行提案执行（ProposalKind::FunctionCall）

函数`internal_execute_proposal()`对于匹配`ProposalKind`为`FunctionCall`的提案实现了如下处理入口：
![14.png](https://img.learnblockchain.cn/attachments/2022/04/839jp6l8626512ae66946.png)

`FunctionCall`类型的提案在提案者调用`add_proposal()`方法之时，便已经通过`ProposalInput`参数传入了具体该提案所要执行的函数操作（`actions`）。

> NEAR 合约允许在一个`Promise`中绑定多个连续的`function_call`。

因此最初提案者设定的`actions`内部可以有如下多种个`ActionCall`对象：

![15.png](https://img.learnblockchain.cn/attachments/2022/04/fm47Ycoi626512cbe7524.png)

每个`ActionCall`可指定相应的合约方法名以及方法参数等。

综上 Sputnik-DAO 采用 `Promise Batch Actions`的形式完成了**合约函数执行**类型提案的执行。

### 3.2 合约资金转移提案执行（ProposalKind::Transfer）

当部署上线的NEAR智能合约项目运行了较长一段时间后，合约账户本身可能已积累了较多的 Fungible Token（包括原生NEAR代币，或其它符合 `NEP-141` 标准的代币）。

此时 Sputnik-DAO 社区成员可通过提交**合约资金转移**提案将这些代币归集到指定的`receiver_id`账户。

同样的`internal_execute_proposal()`对于匹配`ProposalKind`为`Transfer`的提案也实现了相应的处理入口：

![16.png](https://img.learnblockchain.cn/attachments/2022/04/X5kMljZ8626512e8d816b.png)

该处理分支底层将调用`internal_payout()`函数，实现对于不同类型 Fungible Token 以及不同类型`receiver_id`（EOA或者合约账户）的转账操作。

![17.png](https://img.learnblockchain.cn/attachments/2022/04/BESl5qud6265130ae29b1.png)

## 4. 总结与预告

本文已为大家介绍了 Sputnik DAO 合约的核心概念——提案（Proposal），同时也为大家简要说明了如何在 Sputnik DAO 中创建新的提案并投票执行，及其相关提案基本状态（Status）的变化规则。

后续Rust智能合约养成日记将基于提案对 Sputnik-DAO 中治理模式（Policy）的实现与配置展开更为详细的描述，敬请期待！
![640.jpg](https://img.learnblockchain.cn/attachments/2022/04/hnkXLj3Z6265131cc0b72.jpg!/scale/30)

往期回顾：

本期摘要：

Sputnik-DAO 作为 NEAR Protocol 所提供的基础设施，正有力地推动着NEAR生态朝向“去中心化”的目标发展🚀。

目前该平台已促成了众多的NEAR项目“去中心化”自治社区，同时也提供了完整灵活且高效的社区决策治理解决方案。

Sputnikdaov2 🔗是用于 Sputnik-DAO 社区治理投票的智能合约。本期合约代码解读将为大家介绍该合约的核心概念：提案（Proposal），并将在后续的文章中围绕提案介绍相关的DAO社区治理模式（Policy）。

注：本系列智能合约源代码解析，文章的所有内容均不构成任何数字货币投资理财建议。

1. 提案发起（Add Proposal）

深入合约层面，在 Sputnik-DAO 中，DAO社区成员可调用sputnikdaov2合约所提供的add_proposal()方法来发起一个新的提案。

pub fn add_proposal(&mut self, proposal: ProposalInput) -> u64

此时提案者需提供该提案的详细信息（ProposalInput）：

具体含义为：

提案的文字描述（Description）。此段文字信息将公开展示在 Sputnik-DAO 主页前端，帮助社区成员理解该提案的目的与意义。
提案的类型（kind）。提案者需依照对项目管理所提的意见类型进行相应的选择（例如：合约关键特权函数的调用需选择FunctionCall类型，合约项目资金的转移需选择Transfer类型，合约治理权限控制级别"RolePermission"的设置/变更需选择ChangePolicyAddOrUpdateRole等类型）

以上ProposalInput信息将以参数的形式传入add_proposal()方法，随后该方法将进一步执行相关的校验与处理，并生成一个带有完整初始化信息的提案（Proposal）。最终该提案会与唯一的proposal_id相绑定，以<Key, Value>的形式被添加到 Sputnik-DAO 合约全局所维护的 Contract.proposals映射中（提案池）。

如下是 Sputnik-DAO 所定义提案所拥有的完整属性信息：

在该提案中，description与kind属性内容将从proposer在创建该提案所提供的ProposalInput信息中提取。具体为，该合约利用Rust语言 From trait实现了ProposalInput到Proposal的类型转化：

上述转化过程绑定了更多的提案状态信息：

新添加提案中的提案者（proposer）属性会被自动赋值为add_proposal()方法的调用者，即env::predecessor_account_id()，该属性真实且不受用户控制；
新添加的提案状态（status）被默认初始化为ProposalStatus::InProgress，即尚处于投票阶段；
新添加提案的发起时间（submission_time）被赋值为本区块的时间戳 env::block_timestamp()；
由于新提案提交时暂无人投票，因此投票状态（vote_counts, votes）均初始化为空 HashMap::default()。

需要注意的是：Sputnik-DAO 中存在有提案押金（proposal_bond）的概念，该押金将依照具体的 Sputnik-DAO 社区治理模式（Policy）进行管理。

阅读相关代码可知，合约要求提案者在调用add_proposal()方法时质押一定数额的 NEAR 代币作为新提案的保证金。

该笔押金将在提案正常结束（社区投票赞成ProposalStatus::Approved | 社区投票反对ProposalStatus::Rejected）时通过调用合约的内部函数internal_return_bonds()退还给提案人。

然而，BlockSec 此前在解读该处合约代码时发现：

Sputnik-DAO 在处理提案押金时，并没有为每一位用户单独地维护历史提案押金数额 。而当用户发起交易，调用合约方法add_proposal()添加新提案时，可能会给该笔交易附加超过由该 DAO治理策略（Policy）所定义的 policy.bounty_bond NEAR代币 。这将导致多余的部分押金 ，并不会在后续函数internal_return_bonds执行时返还给提案者 。

在 BlockSec Team 及时与项目方取得联系后，最终该 Issue#158 (https://github.com/near-daos/sputnik-dao-contract/issues/158) 被确认并及时在 PR#160 (https://github.com/near-daos/sputnik-dao-contract/pull/160) 中得到修复🙂。

更多 Sputnik-DAO 内部所执行提案相关的校验与处理策略，将在后续推出的《Rust 智能合约养成日记（10-4） Sputnik DAO::社区治理模式剖析》中详细说明。