詳解 EOS 智能合約的 cpp 文件
之前的文章介紹了 eosio.token 智能合約的 hpp 文件,這次向大家介紹 eosio.token.cpp 文件,cpp 文件即 C++ 代碼文件,智能合約所有的業務邏輯內容都是在 cpp 文件中實現的。
eosio.token.cpp 文件地址: https://github.com/EOSIO/eos/blob/master/contracts/eosio.token/eosio.token.cpp
瞭解 C/C++ 開發的同學肯定熟悉,cpp 文件的主要使命是實現 hpp 文件中聲明的函數(方法),包括公有函數(EOS 裏也叫 action)和私有函數。hpp 裏挖的坑,cpp 要一個不留地實現。
私有函數
照慣例,私有函數都是工具函數,供類內部的其他函數調用。
sub_balance(減資產)函數
作用:從指定賬戶中減去資產 參數:被操作賬戶,資產數,資產狀態
// 參數:被操作賬戶 資產種類與數量 資產狀態結構體void token::sub_balance( account_name owner, asset value, const currency_stats& st ) { //建立一個 multi_index,用來操作數據庫 //這裏的參數 _self 表示數據的擁有者爲智能合約本身,參數 owner 表示儲存在名爲被操作賬戶的表中 //這樣並不是直接建立了一個新表,而是讓 C++ 程序與數據庫對應的表之間建立了數據傳輸的通道 accounts from_acnts( _self, owner ); //在數據表中查詢要減少的代幣結構體,就是 hpp 文件中定義的 account 結構體 const auto& from = from_acnts.get( value.symbol.name() ); //校驗,要減少的代幣數量應該小於目前擁有的代幣數量,否則會報錯。 eosio_assert( from.balance.amount >= value.amount, "overdrawn balance" ); //判斷是否有被操作賬戶的授權 if( has_auth( owner ) ) { //校驗,賬戶是否被凍結 eosio_assert( !st.can_freeze || !from.frozen, "account is frozen by issuer" ); //校驗,這種代幣是否被凍結 eosio_assert( !st.can_freeze || !st.is_frozen, "all transfers are frozen by issuer" ); //校驗,賬戶是否在白名單中 eosio_assert( !st.enforce_whitelist || from.whitelist, "account is not white listed" ); //如果沒有被操作賬戶的授權,檢查是否有發幣者的授權 } else if( has_auth( st.issuer ) ) { //如果有發幣者的授權,那麼肯定是在召回代幣,查看代幣是否可以召回 eosio_assert( st.can_recall, "issuer may not recall token" ); } else { //如果兩種授權都沒有,則失敗,沒有足夠的權限 eosio_assert( false, "insufficient authority" ); } //通過 Lambda 表達式(匿名函數)修改將代幣結構體 from_acnts.modify( from, owner, [&]( auto& a ) { //匿名函數 函數體 a.balance -= value; }); }
add_balance(增加資產)函數
作用:從指定賬戶中增加資產 參數:被操作賬戶,資產數,資產狀態,存儲資源支付賬戶
// 參數:被操作賬戶 代幣數量 代幣狀態結構體 儲存支付賬戶void token::add_balance( account_name owner, asset value, const currency_stats& st, account_name ram_payer ) { //建立一個 multi_index,用來操作數據庫 accounts to_acnts( _self, owner ); //在數據表中查詢要增加的代幣結構體 auto to = to_acnts.find( value.symbol.name() ); //如果 to == to_acnts.end(),說明查找到數據表的末尾都沒有對應的結構體,說明該賬戶沒有該代幣 if( to == to_acnts.end() ) { //校驗,該代幣是否開啓了白名單功能 eosio_assert( !st.enforce_whitelist, "can only transfer to white listed accounts" ); //使用 emplace 方法,在數據表中增加一項 to_acnts.emplace( ram_payer, [&]( auto& a ){ //匿名函數體,代幣數量等於每次轉入的數量,因爲之前沒有 a.balance = value; }); //如果數據表中已經存在此項,只需增加代幣數量 } else { //檢查賬戶是否在白名單中 eosio_assert( !st.enforce_whitelist || to->whitelist, "receiver requires whitelist by issuer" ); //使用 modify 方法,修改項目 to_acnts.modify( to, 0, [&]( auto& a ) { //直接修改代幣數量 a.balance += value; }); } }
公有函數
EOS 合約中的公有函數大多是供別的賬戶調用的 Action,根據 hpp 文件,我們需要實現 create、issue、transfer 三個公有函數(action)。
create(新建代幣)函數
create 函數用來創建一種新的代幣,並設置這種新代幣的各種參數。
//參數:發幣賬戶void token::create( account_name issuer, //最大發行量 asset maximum_supply, //發幣者是否可以凍結代幣 uint8_t issuer_can_freeze, //發幣者是否可以召回代幣 uint8_t issuer_can_recall, //是否可以設置白名單 uint8_t issuer_can_whitelist ) { //需要 eosio.token 賬戶本身的授權 require_auth( _self ); auto sym = maximum_supply.symbol; //校驗,新代幣名稱是否有效 eosio_assert( sym.is_valid(), "invalid symbol name" ); //校驗,最大發行量是否有效 eosio_assert( maximum_supply.is_valid(), "invalid supply"); //校驗,最大發行量是否大於零 eosio_assert( maximum_supply.amount > 0, "max-supply must be positive"); //建立一個 milti_index 數據表,用來與數據庫交互 stats statstable( _self, sym.name() ); //在表中搜索相同名稱的代幣 auto existing = statstable.find( sym.name() ); //校驗,是否已經存在相同名稱的代幣 eosio_assert( existing == statstable.end(), "token with symbol already exists" ); //使用 emplace 方法,在數據表中增加一項 statstable.emplace( _self, [&]( auto& s ) { // 使用匿名函數,將傳入的參數賦值給 currency_stats 結構體 s.supply.symbol = maximum_supply.symbol; s.max_supply = maximum_supply; s.issuer = issuer; s.can_freeze = issuer_can_freeze; s.can_recall = issuer_can_recall; s.can_whitelist = issuer_can_whitelist; }); }
transfer(轉賬)函數
transfer 應該是這個智能合約最常用的函數,就是將代幣從一個賬戶轉到另一個。
//轉出方賬戶名void token::transfer( account_name from, //轉入方賬戶名 account_name to, //代幣種類與數量 asset quantity, //轉賬備忘(目前還沒實現) string /*memo*/ ) { //打印轉賬提示 print( "transfer" ); //檢查轉出方權限 require_auth( from ); //得到代幣名稱 auto sym = quantity.symbol.name(); //建立一個 milti_index 數據表,用來與數據庫交互 stats statstable( _self, sym ); //在數據表中尋找代幣的 currency_stats 結構體 const auto& st = statstable.get( sym ); //向轉出方獲取回執 require_recipient( from ); //向轉入方獲取回執 require_recipient( to ); //校驗,轉出的代幣是否有效 eosio_assert( quantity.is_valid(), "invalid quantity" ); //校驗,轉賬數量要大於0 eosio_assert( quantity.amount > 0, "must transfer positive quantity" ); //調用 sub_balance 私有方法 sub_balance( from, quantity, st ); //調用 add_balance 私有方法 add_balance( to, quantity, st, from ); }
issue(發幣)函數
上面的 create 函數創建代幣後只是給定了參數,並沒有真正的代幣被創建出來,需要 issue 函數進行發幣。
//參數:代幣接收方 代幣數量和種類 備忘void token::issue( account_name to, asset quantity, string memo ) { //打印提示 print( "issue" ); //獲取代幣名稱 auto sym = quantity.symbol.name(); //建立一個 milti_index 數據表,用來與數據庫交互 stats statstable( _self, sym ); //在數據表中搜索代幣 currency_stats 結構體 const auto& st = statstable.get( sym ); //檢查發幣者授權 require_auth( st.issuer ); //檢查資產是否有效 eosio_assert( quantity.is_valid(), "invalid quantity" ); //檢查資產是否大於零 eosio_assert( quantity.amount > 0, "must issue positive quantity" ); //檢查創造的總資產是否大於最大代幣數 eosio_assert( quantity <= st.max_supply - st.supply, "quantity exceeds available supply"); //更新資產創造數量記錄 statstable.modify( st, 0, [&]( auto& s ) { s.supply += quantity; }); //給發佈者增加資產 add_balance( st.issuer, quantity, st, st.issuer ); //判斷代幣接受方是否是發幣者 if( to != st.issuer ) { //這裏使用了一個特殊處理,先給發幣者增加相應的代幣,再調用 transfer 函數轉賬給代幣接受方。 //這樣做的目的是讓代幣接受方收到通知 SEND_INLINE_ACTION( *this, transfer, {st.issuer,N(active)}, {st.issuer, to, quantity, memo} ); } }
設置 action
大家知道 EOS 系統的智能合約是以 action 爲基本動作單位的,我們要將需要聲明爲 action 的函數告知 EOS 系統,通過以下宏即可實現。
//將 create issue transfer 三個共有函數聲明爲 action,供其他賬戶調用。EOSIO_ABI( eosio::token, (create)(issue)(transfer) )
End