sysio::multisig Class Reference

#include <sysio.msig.hpp>

Inheritance diagram for sysio::multisig:

Collaboration diagram for sysio::multisig:

Public Types
using	propose_action = sysio::action_wrapper<"propose"_n, &multisig::propose>
using	approve_action = sysio::action_wrapper<"approve"_n, &multisig::approve>
using	unapprove_action = sysio::action_wrapper<"unapprove"_n, &multisig::unapprove>
using	cancel_action = sysio::action_wrapper<"cancel"_n, &multisig::cancel>
using	exec_action = sysio::action_wrapper<"exec"_n, &multisig::exec>
using	invalidate_action = sysio::action_wrapper<"invalidate"_n, &multisig::invalidate>

Public Member Functions
void	propose (ignore< name > proposer, ignore< name > proposal_name, ignore< std::vector< permission_level > > requested, ignore< transaction > trx)
void	approve (name proposer, name proposal_name, permission_level level, const sysio::binary_extension< sysio::checksum256 > &proposal_hash)
void	unapprove (name proposer, name proposal_name, permission_level level)
void	cancel (name proposer, name proposal_name, name canceler)
void	exec (name proposer, name proposal_name, name executer)
void	invalidate (name account)

Detailed Description

The sysio.msig system contract allows for creation of proposed transactions which require authorization from a list of accounts, approval of the proposed transactions by those accounts required to approve it, and finally, it also allows the execution of the approved transactions on the blockchain.

In short, the workflow to propose, review, approve and then executed a transaction it can be described by the following:

• first you create a transaction json file,
• then you submit this proposal to the sysio.msig contract, and you also insert the account permissions required to approve this proposal into the command that submits the proposal to the blockchain,
• the proposal then gets stored on the blockchain by the sysio.msig contract, and is accessible for review and approval to those accounts required to approve it,
• after each of the appointed accounts required to approve the proposed transactions reviews and approves it, you can execute the proposed transaction. The sysio.msig contract will execute it automatically, but not before validating that the transaction has not expired, it is not cancelled, and it has been signed by all the permissions in the initial proposal's required permission list.

Definition at line 19 of file sysio.msig.hpp.

Member Typedef Documentation

approve_action

using sysio::multisig::approve_action = sysio::action_wrapper<"approve"_n, &multisig::approve>

Definition at line 110 of file sysio.msig.hpp.

cancel_action

using sysio::multisig::cancel_action = sysio::action_wrapper<"cancel"_n, &multisig::cancel>

Definition at line 112 of file sysio.msig.hpp.

exec_action

using sysio::multisig::exec_action = sysio::action_wrapper<"exec"_n, &multisig::exec>

Definition at line 113 of file sysio.msig.hpp.

invalidate_action

using sysio::multisig::invalidate_action = sysio::action_wrapper<"invalidate"_n, &multisig::invalidate>

Definition at line 114 of file sysio.msig.hpp.

propose_action

using sysio::multisig::propose_action = sysio::action_wrapper<"propose"_n, &multisig::propose>

Definition at line 109 of file sysio.msig.hpp.

unapprove_action

using sysio::multisig::unapprove_action = sysio::action_wrapper<"unapprove"_n, &multisig::unapprove>

Definition at line 111 of file sysio.msig.hpp.

Member Function Documentation

approve()

void sysio::multisig::approve	(	name	proposer,
		name	proposal_name,
		permission_level	level,
		const sysio::binary_extension< sysio::checksum256 > &	proposal_hash )

Approve action approves an existing proposal. Allows an account, the owner of level permission, to approve a proposal proposal_name proposed by proposer. If the proposal's requested approval list contains the level permission then the level permission is moved from internal requested_approvals list to internal provided_approvals list of the proposal, thus persisting the approval for the proposal_name proposal. Storage changes are billed to proposer.

Parameters

proposer	- The account proposing a transaction
proposal_name	- The name of the proposal (should be unique for proposer)
level	- Permission level approving the transaction
proposal_hash	- Transaction's checksum

Definition at line 59 of file sysio.msig.cpp.

{
   require_auth( level );
 
   if( proposal_hash ) {
      proposals proptable( get_self(), proposer.value );
      auto& prop = proptable.get( proposal_name.value, "proposal not found" );
      assert_sha256( prop.packed_transaction.data(), prop.packed_transaction.size(), *proposal_hash );
   }
 
   approvals apptable( get_self(), proposer.value );
   auto apps_it = apptable.find( proposal_name.value );
   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; } );
      check( 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( get_self(), proposer.value );
      auto& apps = old_apptable.get( proposal_name.value, "proposal not found" );
 
      auto itr = std::find( apps.requested_approvals.begin(), apps.requested_approvals.end(), level );
      check( 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 );
         });
   }
}

cancel()

void sysio::multisig::cancel	(	name	proposer,
		name	proposal_name,
		name	canceler )

Cancel action cancels an existing proposal.

Parameters

proposer	- The account proposing a transaction
proposal_name	- The name of the proposal (should be an existing proposal)
canceler	- The account cancelling the proposal (only the proposer can cancel an unexpired transaction, and the canceler has to be different than the proposer)

Allows the canceler account to cancel the proposal_name proposal, created by a proposer, only after time has expired on the proposed transaction. It removes corresponding entries from internal proptable and from approval (or old approvals) tables as well.

Definition at line 118 of file sysio.msig.cpp.

                                                                        {
   require_auth( canceler );
 
   proposals proptable( get_self(), proposer.value );
   auto& prop = proptable.get( proposal_name.value, "proposal not found" );
 
   if( canceler != proposer ) {
      check( unpack<transaction_header>( prop.packed_transaction ).expiration < sysio::time_point_sec(current_time_point()), "cannot cancel until expiration" );
   }
   proptable.erase(prop);
 
   //remove from new table
   approvals apptable( get_self(), proposer.value );
   auto apps_it = apptable.find( proposal_name.value );
   if ( apps_it != apptable.end() ) {
      apptable.erase(apps_it);
   } else {
      old_approvals old_apptable( get_self(), proposer.value );
      auto apps_it = old_apptable.find( proposal_name.value );
      check( apps_it != old_apptable.end(), "proposal not found" );
      old_apptable.erase(apps_it);
   }
}

exec()

void sysio::multisig::exec	(	name	proposer,
		name	proposal_name,
		name	executer )

Exec action allows an executer account to execute a proposal.

Preconditions:

• executer has authorization,
• proposal_name is found in the proposals table,
• all requested approvals are received,
• proposed transaction is not expired,
• and approval accounts are not found in invalidations table.

If all preconditions are met the transaction is executed as a deferred transaction, and the proposal is erased from the proposals table.

Parameters

proposer	- The account proposing a transaction
proposal_name	- The name of the proposal (should be an existing proposal)
executer	- The account executing the transaction

Definition at line 142 of file sysio.msig.cpp.

                                                                      {
   require_auth( executer );
 
   proposals proptable( get_self(), proposer.value );
   auto& prop = proptable.get( proposal_name.value, "proposal not found" );
   transaction_header trx_header;
   datastream<const char*> ds( prop.packed_transaction.data(), prop.packed_transaction.size() );
   ds >> trx_header;
   check( trx_header.expiration >= sysio::time_point_sec(current_time_point()), "transaction expired" );
 
   approvals apptable( get_self(), proposer.value );
   auto apps_it = apptable.find( proposal_name.value );
   std::vector<permission_level> approvals;
   invalidations inv_table( get_self(), get_self().value );
   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.value );
         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( get_self(), proposer.value );
      auto& apps = old_apptable.get( proposal_name.value, "proposal not found" );
      for ( auto& level : apps.provided_approvals ) {
         auto it = inv_table.find( level.actor.value );
         if ( it == inv_table.end() ) {
            approvals.push_back( level );
         }
      }
      old_apptable.erase(apps);
   }
   auto 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()
               );
 
   check( res > 0, "transaction authorization failed" );
 
   send_deferred( (uint128_t(proposer.value) << 64) | proposal_name.value, executer,
                  prop.packed_transaction.data(), prop.packed_transaction.size() );
 
   proptable.erase(prop);
}

invalidate()

void sysio::multisig::invalidate

(

name

account

)

Invalidate action allows an account to invalidate itself, that is, its name is added to the invalidations table and this table will be cross referenced when exec is performed.

Parameters

account

- The account invalidating the transaction

Definition at line 191 of file sysio.msig.cpp.

                                        {
   require_auth( account );
   invalidations inv_table( get_self(), get_self().value );
   auto it = inv_table.find( account.value );
   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();
         });
   }
}

propose()

void sysio::multisig::propose	(	ignore< name >	proposer,
		ignore< name >	proposal_name,
		ignore< std::vector< permission_level > >	requested,
		ignore< transaction >	trx )

Propose action, creates a proposal containing one transaction. Allows an account proposer to make a proposal proposal_name which has requested permission levels expected to approve the proposal, and if approved by all expected permission levels then trx transaction can we executed by this proposal. The proposer account is authorized and the trx transaction is verified if it was authorized by the provided keys and permissions, and if the proposal name doesn’t already exist; if all validations pass the proposal_name and trx trasanction are saved in the proposals table and the requested permission levels to the approvals table (for the proposer context). Storage changes are billed to proposer.

Parameters

proposer	- The account proposing a transaction
proposal_name	- The name of the proposal (should be unique for proposer)
requested	- Permission levels expected to approve the proposal
trx	- Proposed transaction

Definition at line 9 of file sysio.msig.cpp.

{
   name _proposer;
   name _proposal_name;
   std::vector<permission_level> _requested;
   transaction_header _trx_header;
 
   _ds >> _proposer >> _proposal_name >> _requested;
 
   const char* trx_pos = _ds.pos();
   size_t size    = _ds.remaining();
   _ds >> _trx_header;
 
   require_auth( _proposer );
   check( _trx_header.expiration >= sysio::time_point_sec(current_time_point()), "transaction expired" );
   //check( trx_header.actions.size() > 0, "transaction must have at least one action" );
 
   proposals proptable( get_self(), _proposer.value );
   check( proptable.find( _proposal_name.value ) == proptable.end(), "proposal with the same name exists" );
 
   auto packed_requested = pack(_requested);
   auto res =  check_transaction_authorization(
                  trx_pos, size,
                  (const char*)0, 0,
                  packed_requested.data(), packed_requested.size()
               );
 
   check( res > 0, "transaction authorization failed" );
 
   std::vector<char> pkd_trans;
   pkd_trans.resize(size);
   memcpy((char*)pkd_trans.data(), trx_pos, size);
   proptable.emplace( _proposer, [&]( auto& prop ) {
      prop.proposal_name       = _proposal_name;
      prop.packed_transaction  = pkd_trans;
   });
 
   approvals apptable( get_self(), _proposer.value );
   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} } } );
      }
   });
}

Here is the call graph for this function:

unapprove()

void sysio::multisig::unapprove	(	name	proposer,
		name	proposal_name,
		permission_level	level )

Unapprove action revokes an existing proposal. This action is the reverse of the approve action: if all validations pass the level permission is erased from internal provided_approvals and added to the internal requested_approvals list, and thus un-approve or revoke the proposal.

Parameters

proposer	- The account proposing a transaction
proposal_name	- The name of the proposal (should be an existing proposal)
level	- Permission level revoking approval for proposal

Definition at line 94 of file sysio.msig.cpp.

                                                                                    {
   require_auth( level );
 
   approvals apptable( get_self(), proposer.value );
   auto apps_it = apptable.find( proposal_name.value );
   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; } );
      check( 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( get_self(), proposer.value );
      auto& apps = old_apptable.get( proposal_name.value, "proposal not found" );
      auto itr = std::find( apps.provided_approvals.begin(), apps.provided_approvals.end(), level );
      check( 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 );
         });
   }
}

---

The documentation for this class was generated from the following files:

• /Users/svetlasyrimis/Desktop/wire-network/WN-org/wire-system-contracts/contracts/sysio.msig/include/sysio.msig/sysio.msig.hpp
• /Users/svetlasyrimis/Desktop/wire-network/WN-org/wire-system-contracts/contracts/sysio.msig/src/sysio.msig.cpp