Smart Contract Handbook

Overview

For the request of agile development and concepts verifying, IOST Testnet uses Lua as our extensible smart contract programming language. And a pre-compiler is provided to add or remove features of original Lua script.

Supported features list below:

1. On blockchain storage of key-value pair, vector types like Lua table supported
2. IOST transfer
3. Deposit to or Withdraw from contract account
4. Inter-contract API calls
5. Multi signature

Some of Lua's feature such as require are not supported yet, and will be supported during next updates.

Ruler of Gas

An EVM-like Gas system will be used to solve halting problem，and pay to nodes.

The PUBLISHER will pay the contract fee, which equals actually gas cost multiplied by annonced gas price.

At least 0.01 IOST will be charged for each transaction to avoid hostile attack.

Way to Publish Transactions

Use iwallet -h for more infomations.

1. Compile source code to .sc file. iwallet compile <lua_file>
2. (optional) Sign .sc file as participant. iwallet sign <sc_file>
3. Publish smart contract. iwallet publish <sc_file> [sig_file]

API

IOST smart contract is an API oriental smart contract, API declaration looks like below.

--- main
-- your own comments
-- @gas_limit 11
-- @gas_price 0.0001
-- @param_cnt 0
-- @return_cnt 1
function main()
    Put("hello", "world")
    return "success"
end--f
--- sayHi
-- @param_cnt 1
-- @return_cnt 1
function sayHi(name)
    return "hi " .. name
end--f

Pre-compiler will read comments after ---, and args in comments will be loaded. Attention：function definition should end with "end--f"

Definition of args:

--- <function_name>   name of API
-- @param_cnt         counts of params
-- @return_cnt        counts of return value
-- @gas_limit         Gas limit, only the first declaration of a file will be used. 
-- @gas_price         Gas price, act as above
-- @privilege         Privilege of API, default _public_

IOST currently support private and public . public means it could be called by everyone, and private means only PUBLISHER of this contract could call it (in inter-contract call).

Further privilege control will be add in future

A main function must be provided in contract. It will be called ONCE when transaction accepted on blockchain. the param count in main function is 0, and return value will be aborted.

Do not use anything outside function, for those codes will be clear in pre-compile phase.

IOST API

Put(key, value) -> bool               -- Write key-value pair to blockchain，only float，string are support
Get(key) -> bool, value               -- Read value of a key, which written by contract itself
Transfer(from, to, account) -> bool                     -- IOST transfer，sender's signature should included
Call(ContractID, apiName, args) -> bool, value...       -- inter-contract call, return API's returns
Deposit(from, value) -> bool          -- deposit IOST to contract account
Withdraw(to, value)  -> bool          -- get IOST from contract account
Random(probability)  -> number        -- give probability and return a blockchain-random true/false result
Now() -> value                        -- return timestamp in seconds
Witness() -> string                   -- return current block's witness, in base 58 encode
Height() -> number                    -- return height of block
ParentHash() -> number                -- return last byte of parent hash
ToJson(table) -> bool, jsonStr        -- convert lua table to a json string
ParseJson(jsonStr) -> bool, table     -- parse lua table from a json string

Playground

Playground is a debug tool of IOST smart contract. Input init values and source codes, and result will be printed.

Usage

playground [-v init_values.yml] [source_code_1][source_code_2]...

flag -v specified .yaml files which imply init variant, source codes will be compiled and run by order. you can see more by using playground -h