I spend some time learning about developing EOS contracts. I still have lot’s of to learn but I would like to share what I already know. I hop it will let you save some time.
All the code there was created for dawn-2.x. Dawn 3 is in a master branch and have many nice improvements but it’s in development and many things not work correctly. Because of this I think it is better to start with dawn 2 and then switch to 3.
General contract concept
In general EOS contract is a small application associated with specific account. We communicate with it by sending messages to the account.
Additionally contract my store data in EOS blockchain using tables. You may think about table as a type of key-value storage where value is just a array of bytes. You have guarantee that information stored there will be persistent and you want loos them. Contract may read and write to tables. Those tables can also be query from outside a contract using, in example, command line (eosc get table).
Use case
Let’s say I developed contract responsible for managing users in my application. One of functionality of this contract is to register new user. To do this I have to send message (action) named “newuser” with all the details about new user.
Previously I created account called “myappusers”…
eosc create account myotheraccount myappusers EOS774sYPbScdKxUZsf6sH4B7qLdEbjJuMeyPG6vDZBmJ17AwDLzV 5HxRSY9mG1UzSd5fxJpqWgEwBt9Jt6Cwo3pe12D3KbgucDvzHMeand deployed contract to this account…
eosc set contract myappusers users_manager.wasm users_manager.abiand now I just have to send message to this account and it will be processed by contract.
eosc push message myappusers newuser '{ "login": "mike23", "password": "password1", "email": "[email protected]", "details": { "age": 26, "first_name": "Michael", "last_name": "Wazowski" } }' --scope myappusersImplementation
- Generate new project from scaffold
- Define messages in hpp file
- Generate abi and gen.hpp files
- Update implementation in cpp file
Generate new project from scaffold
Using eoscpp you can create basic contract.
eoscpp -n user_management_contractThis command will create new folder, named “user_management_contract”, containing three files:
- user_management_contract.abi
- user_management_contract.hpp
- user_management_contract.cpp
In moment I writing this, generated abi file is wrong (I think it’s content coming from currency contract) so just delete it.
Define messages in hpp file
Next we have to define messages I want my contract to support. For every one I have to define struct with required fields. In my case just one, newuser. My user_management_contract.hpp looks like this:
#include <eoslib/eos.hpp>
#include <eoslib/db.hpp>
#include <eoslib/string.hpp>
struct user_data {
uint8_t age;
eosio::string first_name;
eosio::string last_name;
};
// @abi action newuser
struct newuser {
eosio::string login;
eosio::string password;
eosio::string email;
user_data details;
};
In this file I have two structures: newuser and user_data. In structures defining messages you can only use subset of types. In practice in dawn-2.x only integers and strings (eosio::string). You may also have field using other structure, like details field in newuser struct using user_data.
When we sending message to contract we using json format
eosc push message myappusers newuser '{ "login": "mike23", "password": "password1", "email": "[email protected]", "details": { "age": 26, "first_name": "Michael", "last_name": "Wazowski" } }' --scope myappusersMy message content looks like this
{
"login":"mike23",
"password":"password1",
"email":"[email protected]",
"details":{
"age":26,
"first_name":"Michael",
"last_name":"Wazowski"
}
}How you can see fields in json matches those in newuse and user_data structures but to map one to another we need more precise description how to do this.
This is responsibility of abi file. It describes to what C/C++ types specific fields should be mapped. Abi file is generated by eoscpp from hpp file.
Generate abi and gen.hpp files
eoscpp -g user_management_contract.abi -gs user_management_contract.hppAbi generator recognizes structures to map looking for comments before structure. In my case newuser is marked as action named “newuser”
// @abi action newuser
struct newuser {
...If you check other contracts in eos project you will find also comments like “@abi table sometablename”. This define mapping for tables but I’m still not fully understand how to use them so I will skip it for now.
After this my new user_management_contract.abi looks like this
{
"types": [],
"structs": [{
"name": "user_data",
"base": "",
"fields": {
"age": "uint8",
"first_name": "string",
"last_name": "string"
}
},{
"name": "newuser",
"base": "",
"fields": {
"login": "string",
"password": "string",
"email": "string",
"details": "user_data"
}
}
],
"actions": [{
"action_name": "newuser",
"type": "newuser"
}
],
"tables": []
}eoscpp also generate second file named user_management_contract.gen.hpp. This file contains C++ code responsible for serializing and deserializing our structures.
Update implementation in cpp file
Now when we have all files we can modify user_management_contract.cpp to process our message.
In this file you will find function looks like this
void apply( uint64_t code, uint64_t action ) {
eosio::print( "Hello World: ", eosio::name(code), "->", eosio::name(action), "\n" );
}Every time you send message to the contract EOS call this function. In it we have to:
- Recognize is message directed to us
- Recognize action
- Extract received message
Modified apply function may looks like this
using namespace myappusers
void apply( uint64_t code, uint64_t action ) {
// Recognize is message directed to us
if(code==N(myappusers)){
// Recognize action
if(action==N(newuser)){
// Extract received message
auto nu = eosio::current_message<newuser>();
eosio::print("Add new user message");
eosio::dump(nu);
}else
eosio::print("Unknown action");
}
}
}
Two function in apply (eosio::current_message<newuser> and eosio::dump) coming from user_management_contract.gen.hpp file so don't forget to include it (add at the beginning of cpp file '#include "user_management_contract.gen.hpp"' ).
This contract doesn’t do anything useful, just print received message but it good starting point.
I didn’t put there any code interaction with tables because there are still to many things that I don’t understand :(
If you found something wrong or have question feel free to let me know in comments.