docs/group__contractdev.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>EOS.IO: Smart Contract API Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="eos-logo.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">EOS.IO
   &#160;<span id="projectnumber">DAWN3.0.1</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#groups">Modules</a>  </div>
  <div class="headertitle">
<div class="title">Smart Contract API Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p>Introduction to writing contracts for EOS.IO.  
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="groups"></a>
Modules</h2></td></tr>
<tr class="memitem:group__accountapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__accountapi.html">Account API</a></td></tr>
<tr class="memdesc:group__accountapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Define API for querying account data. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__actionapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__actionapi.html">Action API</a></td></tr>
<tr class="memdesc:group__actionapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Define API for querying action properties. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__chainapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__chainapi.html">Chain API</a></td></tr>
<tr class="memdesc:group__chainapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Define API for querying internal chain state. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__database"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__database.html">Database API</a></td></tr>
<tr class="memdesc:group__database"><td class="mdescLeft">&#160;</td><td class="mdescRight">APIs that store and retreive data on the blockchainEOS.IO organizes data according to the following broad structure: <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__mathapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__mathapi.html">Math API</a></td></tr>
<tr class="memdesc:group__mathapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Defines common math functions. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__memoryapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__memoryapi.html">Memory API</a></td></tr>
<tr class="memdesc:group__memoryapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Defines common memory functions. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__consoleapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__consoleapi.html">Console API</a></td></tr>
<tr class="memdesc:group__consoleapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Enables applications to log/print text messages. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__systemapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__systemapi.html">System API</a></td></tr>
<tr class="memdesc:group__systemapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Define API for interating with system level intrinsics. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__tokens"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__tokens.html">Token API</a></td></tr>
<tr class="memdesc:group__tokens"><td class="mdescLeft">&#160;</td><td class="mdescRight">Defines the ABI for interfacing with standard-compatible token messages and database tables. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__transactionapi"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__transactionapi.html">transaction API</a></td></tr>
<tr class="memdesc:group__transactionapi"><td class="mdescLeft">&#160;</td><td class="mdescRight">Define API for sending transactions and inline messages. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:group__types"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__types.html">Builtin Types</a></td></tr>
<tr class="memdesc:group__types"><td class="mdescLeft">&#160;</td><td class="mdescRight">Specifies typedefs and aliases. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h1><a class="anchor" id="background"></a>
Background</h1>
<p>EOS.IO contracts (aka applications) are deployed to a blockchain as pre-compiled Web Assembly (aka WASM). WASM is compiled from C/C++ using LLVM and clang, which means that you will require knowledge of C/C++ in order to develop your blockchain applications. While it is possible to develop in C, we strongly recommend that all developers use the EOS.IO C++ API which provides much stronger type safety and is generally easier to read.</p>
<h1><a class="anchor" id="programstructure"></a>
Application Structure</h1>
<p>EOS.IO applications are designed around event (aka action) handlers that respond to user actions. For example, a user might transfer tokens to another user. This event can be processed and potentially rejected by the sender, the receiver, and the currency application itself.</p>
<p>As an application developer you get to decide what actions users can take and which handlers may or must be called in response to those events.</p>
<h2><a class="anchor" id="programentry"></a>
Entry Points</h2>
<p>EOS.IO applications have a <code>apply</code> which is like <code>main</code> in traditional applications:</p>
<div class="fragment"><div class="line"><span class="keyword">extern</span> <span class="stringliteral">&quot;C&quot;</span> {</div><div class="line">   <span class="keywordtype">void</span> <a class="code" href="namespaceeosiosystem.html#a3ea5c4b8e36e422e6dd7f2e60ffd6fd4">init</a>();</div><div class="line">   <span class="keywordtype">void</span> <a class="code" href="asserter_8cpp.html#a3c01edc4ed313916967237c16feb1446">apply</a>( <a class="code" href="group__types.html#gaaa5d1cd013383c889537491c3cfd9aad">uint64_t</a> code, <a class="code" href="group__types.html#gaaa5d1cd013383c889537491c3cfd9aad">uint64_t</a> action );</div><div class="line">}</div></div><!-- fragment --><p><code>apply</code> is give the arguments <code>code</code> and <code>action</code> which uniquely identify every event in the system. For example, <code>code</code> could be a <em>currency</em> contract and <code>action</code> could be <em>transfer</em>. This event (code,action) may be passed to several contracts including the <code>sender</code> and <code>receiver</code>. It is up to your application to figure out what to do in response to such an event.</p>
<p><code>init</code> is another entry point that is called once immediately after loading the code. It is where you should perform one-time initialization of state.</p>
<h3>Example Apply Entry Handler</h3>
<p>Generally speaking, you should use your entry handler to dispatch events to functions that implement the majority of your logic and optionally reject events that your contract is unable or unwilling to accept.</p>
<div class="fragment"><div class="line"><span class="keyword">extern</span> <span class="stringliteral">&quot;C&quot;</span> {</div><div class="line">   <span class="keywordtype">void</span> <a class="code" href="asserter_8cpp.html#a3c01edc4ed313916967237c16feb1446">apply</a>( <a class="code" href="group__types.html#gaaa5d1cd013383c889537491c3cfd9aad">uint64_t</a> code, <a class="code" href="group__types.html#gaaa5d1cd013383c889537491c3cfd9aad">uint64_t</a> action ) {</div><div class="line">      <span class="keywordflow">if</span>( code == <a class="code" href="group__types.html#gaf9c1edb0e0da55ec6ba09f32f6839529">N</a>(<a class="code" href="namespacecurrency.html">currency</a>) ) {</div><div class="line">         <span class="keywordflow">if</span>( action == <a class="code" href="group__types.html#gaf9c1edb0e0da55ec6ba09f32f6839529">N</a>(transfer) ) </div><div class="line">            <a class="code" href="namespaceexchange.html#a32b7d74a91010152d37cace85418e6f7">currency::apply_currency_transfer</a>( current_action&lt; currency::transfer &gt;() );</div><div class="line">      } <span class="keywordflow">else</span> {</div><div class="line">         <a class="code" href="group__systemcapi.html#gae2a6ebaf48fe7c69f847ae18f109d09a">assert</a>( <span class="keyword">false</span>, <span class="stringliteral">&quot;rejecting unexpected event&quot;</span> );</div><div class="line">      }</div><div class="line">   }</div><div class="line">}</div></div><!-- fragment --><dl class="section note"><dt>Note</dt><dd>When defining your entry points it is required that they are placed in an <code>extern "C"</code> code block so that c++ name mangling does not get applied to the function. </dd></dl>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>