eos系统合约介绍 — 提案合约eosio.msig (下)
简介
本篇将为大家介绍eosio.msig的源码实现，合约代码库详见：eosio.msig。eosio.msig主要有propose、approve、unapprove、cancel、exec、invalidate这几种方法，下面会详细逐一介绍每种方法的功能和实现细节。
主要合约方法
eosio.msig合约，在eosio.msig.hpp头文件中，主要定义了以下六个合约方法：
- propose：提出提案
- approve：通过提案
- unapprove：不通过提案
- cancel：取消提案
- exec：执行提案
- invalidate：撤回对之前所有该账户通过、但未被最终执行的提案的通过授权
eosio.msig合约头文件
namespace eosio {
class multisig : public contract {
public:
multisig( account_name self ):contract(self){}
void propose();
void approve( account_name proposer, name proposal_name, permission_level level );
void unapprove( account_name proposer, name proposal_name, permission_level level );
void cancel( account_name proposer, name proposal_name, account_name canceler );
void exec( account_name proposer, name proposal_name, account_name executer );
void invalidate( account_name account );propose方法
propose方法主要功能是提出提案，对应上篇提到的 cleos multisig propose 命令，传参如下：
- proposer：提案账户
- proposal_name：提案名
- requested：提案通过所需权限
- trx：提案具体执行的交易内容
为了节省资源开销，propose方法并不会根据 cleos multisig propose 传入的参数一一做解析，而是直接解析input data
/*
propose function manually parses input data (instead of taking parsed arguments from dispatcher)
because parsing data in the dispatcher uses too much CPU in case if proposed transaction is big
If we use dispatcher the function signature should be:
void multisig::propose( account_name proposer,
name proposal_name,
vector<permission_level> requested,
transaction trx)
*/
void multisig::propose() {
constexpr size_t max_stack_buffer_size = 512;
size_t size = action_data_size();
char* buffer = (char*)( max_stack_buffer_size < size ? malloc(size) : alloca(size) );
read_action_data( buffer, size );之后，会做一系列前置检验工作：proposer提案账户授权是否正确、交易是否超时、propose_name是否存在、提案通过所需权限是否正确等
require_auth( proposer );
eosio_assert( trx_header.expiration >= eosio::time_point_sec(current_time_point()), "transaction expired" );
//eosio_assert( trx_header.actions.size() > 0, "transaction must have at least one action" );
proposals proptable( _self, proposer );
eosio_assert( proptable.find( proposal_name ) == proptable.end(), "proposal with the same name exists" );
bytes packed_requested = pack(requested);
auto res = ::check_transaction_authorization( buffer+trx_pos, size-trx_pos,
(const char*)0, 0,
packed_requested.data(), packed_requested.size()
);
eosio_assert( res > 0, "transaction authorization failed" );之后，将提案和提案合约的内容存表，将提案通过所需的权限存入requested_approvals表中，我们上篇文章所提到 cleos get table eosio.msig <proposer account> approvals 命令查询的就是这张表
proptable.emplace( proposer, [&]( auto& prop ) {
prop.proposal_name = proposal_name;
prop.packed_transaction = bytes( buffer+trx_pos, buffer+size );
});
approvals apptable( _self, proposer );
apptable.emplace( proposer, [&]( auto& a ) {
a.proposal_name = proposal_name;
a.requested_approvals.reserve( requested.size() );
for ( auto& level : requested ) {
a.requested_approvals.push_back( approval{ level, time_point{ microseconds{0} } } );
}
});approve方法
approve方法的主要功能是通过提案，对应上篇提到的 cleos multisig approve 命令，传参如下
- proposer：提案人
- proposal_name：提案名
- permissions：使用哪个权限批准这个提案
首先，系统会查找提案合约内容，查找 requested_approvals 表中需要通过的权限中，是否有和传入permission匹配项。若有匹配项，将此权限加入 provided_approvals 表，即表示该权限通过此提案，并从 requested_approvals 表中移除该权限。
void multisig::approve( account_name proposer, name proposal_name, permission_level level ) {
require_auth( level );
approvals apptable( _self, proposer );
auto apps_it = apptable.find( proposal_name );
if ( apps_it != apptable.end() ) {
auto itr = std::find_if( apps_it->requested_approvals.begin(), apps_it->requested_approvals.end(), [&](const approval& a) { return a.level == level; } );
eosio_assert( itr != apps_it->requested_approvals.end(), "approval is not on the list of requested approvals" );
apptable.modify( apps_it, proposer, [&]( auto& a ) {
a.provided_approvals.push_back( approval{ level, current_time_point() } );
a.requested_approvals.erase( itr );
});
} else {
old_approvals old_apptable( _self, proposer );
auto& apps = old_apptable.get( proposal_name, "proposal not found" );
auto itr = std::find( apps.requested_approvals.begin(), apps.requested_approvals.end(), level );
eosio_assert( itr != apps.requested_approvals.end(), "approval is not on the list of requested approvals" );
old_apptable.modify( apps, proposer, [&]( auto& a ) {
a.provided_approvals.push_back( level );
a.requested_approvals.erase( itr );
});
}
}unapprove方法
unapprove方法的主要功能是不通过提案，对应上篇提到的 cleos multisig unapprove 命令，传参如下：
- proposer：提案人
- proposal_name：提案名
- permissions：使用哪个权限拒绝这个提案
首先，系统会查找提案合约内容，查找 provided_approvals 表中通过的权限中，是否有和传入permission匹配项。若有匹配项，将此权限加入requested_approvals 表，即表示该权限还没通过此提案，并从 provided_approvals 表中移除该权限。
void multisig::unapprove( account_name proposer, name proposal_name, permission_level level ) {
require_auth( level );
approvals apptable( _self, proposer );
auto apps_it = apptable.find( proposal_name );
if ( apps_it != apptable.end() ) {
auto itr = std::find_if( apps_it->provided_approvals.begin(), apps_it->provided_approvals.end(), [&](const approval& a) { return a.level == level; } );
eosio_assert( itr != apps_it->provided_approvals.end(), "no approval previously granted" );
apptable.modify( apps_it, proposer, [&]( auto& a ) {
a.requested_approvals.push_back( approval{ level, current_time_point() } );
a.provided_approvals.erase( itr );
});
} else {
old_approvals old_apptable( _self, proposer );
auto& apps = old_apptable.get( proposal_name, "proposal not found" );
auto itr = std::find( apps.provided_approvals.begin(), apps.provided_approvals.end(), level );
eosio_assert( itr != apps.provided_approvals.end(), "no approval previously granted" );
old_apptable.modify( apps, proposer, [&]( auto& a ) {
a.requested_approvals.push_back( level );
a.provided_approvals.erase( itr );
});
}
}cancel方法
cancel方法的主要功能是取消提案，对应上篇提到的 cleos multisig cancel 命令，传参如下：
- proposer：提案账户
- proposal_name：提案名
- canceler：取消账户
首先，先查找表获取提案内容。如果canceler账户和提案账户不同，则在提案交易过期之前，canceler都不能取消提案。若能取消，将提案从表中移除。
void multisig::cancel( account_name proposer, name proposal_name, account_name canceler ) {
require_auth( canceler );
proposals proptable( _self, proposer );
auto& prop = proptable.get( proposal_name, "proposal not found" );
if( canceler != proposer ) {
eosio_assert( unpack<transaction_header>( prop.packed_transaction ).expiration < eosio::time_point_sec(current_time_point()), "cannot cancel until expiration" );
}
proptable.erase(prop);
//remove from new table
approvals apptable( _self, proposer );
auto apps_it = apptable.find( proposal_name );
if ( apps_it != apptable.end() ) {
apptable.erase(apps_it);
} else {
old_approvals old_apptable( _self, proposer );
auto apps_it = old_apptable.find( proposal_name );
eosio_assert( apps_it != old_apptable.end(), "proposal not found" );
old_apptable.erase(apps_it);
}
}exec方法
exec方法的主要功能是执行提案，对应上篇提到的 cleos multisig exec 命令，传参如下：
- proposer：提案账户
- proposal_name：提案名
- executer：执行账户
void multisig::exec( account_name proposer, name proposal_name, account_name executer ) {
require_auth( executer );
proposals proptable( _self, proposer );
auto& prop = proptable.get( proposal_name, "proposal not found" );
transaction_header trx_header;
datastream<const char*> ds( prop.packed_transaction.data(), prop.packed_transaction.size() );
ds >> trx_header;
//首先，需要做前置检查，检查交易是否过期
eosio_assert( trx_header.expiration >= eosio::time_point_sec(current_time_point()), "transaction expired" );
approvals apptable( _self, proposer );
auto apps_it = apptable.find( proposal_name );
vector<permission_level> approvals;
//然后，查 provided_approvals 表获取通过提案交易的权限们，对比 inv_table 表，如果权限不在 inv_table 表中或者 last_invalidation_time
//已经小于当前时间，代表权限有效，放入approvals表中。inv_table 表的用途在下一个invalidate方法中介绍
invalidations inv_table( _self, _self );
if ( apps_it != apptable.end() ) {
approvals.reserve( apps_it->provided_approvals.size() );
for ( auto& p : apps_it->provided_approvals ) {
auto it = inv_table.find( p.level.actor );
if ( it == inv_table.end() || it->last_invalidation_time < p.time ) {
approvals.push_back(p.level);
}
}
apptable.erase(apps_it);
} else {
old_approvals old_apptable( _self, proposer );
auto& apps = old_apptable.get( proposal_name, "proposal not found" );
for ( auto& level : apps.provided_approvals ) {
auto it = inv_table.find( level.actor );
if ( it == inv_table.end() ) {
approvals.push_back( level );
}
}
old_apptable.erase(apps);
}
//最后，执行提案。如果交易执行权限检验无误，会发起一个defer延迟合约，去执行提案交易。如果执行成功，
//`cleos get actions <executer account>` 会产生两条actions，一条是exec的交易，一条是提案执行的交易。
bytes packed_provided_approvals = pack(approvals);
auto res = ::check_transaction_authorization( prop.packed_transaction.data(), prop.packed_transaction.size(),
(const char*)0, 0,
packed_provided_approvals.data(), packed_provided_approvals.size()
);
eosio_assert( res > 0, "transaction authorization failed" );
send_deferred( (uint128_t(proposer) << 64) | proposal_name, executer, prop.packed_transaction.data(), prop.packed_transaction.size() );
proptable.erase(prop);
}invalidate方法
invalidate方法的主要功能是：如果account之前通过的提案还未执行，就可以使用该方法将提案一键设置为无效。这个方法主要是解决：账户权限变更时，之前通过但未执行的提案一旦执行会盗取账户权限的问题，详见issue。该方法传参如下：
- account：提案的批准账户
该功能的实现非常简单，首先，inv_table 是用来存放权限的，它的两个字段 account 和last_invalidation_time 分别是账户名和账户权限最近失效时间。last_invalidation_time 时间之前，account的提案批准权限都不可用，在该时间之后account的提案批准权限才能生效。
因此，如果想使account之前审批通过的所有提案都失效的话，就将 last_invalidation_time 设置为当前时间即可。exec方法在执行之前会检查 inv_table，则包含在 inv_table 中的account，即便批准了该提案，该批准也会作废
void multisig::invalidate( account_name account ) {
require_auth( account );
invalidations inv_table( _self, _self );
auto it = inv_table.find( account );
if ( it == inv_table.end() ) {
inv_table.emplace( account, [&](auto& i) {
i.account = account;
i.last_invalidation_time = current_time_point();
});
} else {
inv_table.modify( it, account, [&](auto& i) {
i.last_invalidation_time = current_time_point();
});
}
}转载自简书