Introduction to BUMO smart contract

Definition

Attention: Recommend a New Smart Contract Interfaces for development.

Smart Contract is a section of ECMAScript as specified in ECMA-262. The codes of smart contract should contain two parts of functions. The first is initialization function, init. The other one is entry function, main. When you call the main function you have to assign the input (type string). For syntax, please referring to Contract Syntax.

The following is a simple example:

"use strict";
function init(bar)
{
  /*init whatever you want*/
  return;
}

function main(input)
{
  let para = JSON.parse(input);
  if (para.do_foo)
  {
    let x = {
      'hello' : 'world'
    };
  }
}

function query(input)
{ 
  return input;
}

Global Functions and Default Variables

Do not duplicate the name of Global Functions or Default Variables as the custom fuctions. It will lead to uncontrollable error.

Global Functions

The system offers several global variables for getting the information of blockchain and drive the transactions, except setting thresholds and weight.

Read/Write Rights of functions

Every functions have a stable read-only or write authority:

Read-only means the interface functions which would not write the data on the blockchain, such as getBalance.
Write means the interface functions which would write data on the blockchain, such as transferring payCoin.

While coding the smart contract, please pay attention to the authority for calling different entry functions:

init and main functions can call all the global functions.
query can only call the read-only functions. Or the interface will be undefined during debugging or execution.

Return

For all the default functions, if they fail, then, return false or throw the exceptions directly. Otherwise, they will return other objects.If there is a parameter error, the error description will describe the parameter location, which refers to the index number of the parameter, i.e., counting from 0. e.g.

issueAsset("CNY", 10000);
/*
   error description:
   Contract execute error,issueAsset parameter 1 should be a string

   Means that the second argument should be a string
*/

Details

This chapter mainly introduces some functions involved in the development process of smart contract, including assert、getBalance、storageStore、storageLoad、storageDel、getAccountAsset、getBlockHash、addressCheck、stoI64Check、int64Add、int64Sub、int64Mul、int64Div、int64Mod、int64Compare、toBaseUnit、log、tlog、issueAsset、payAsset、payCoin.

assert

Description

assert Function for assertion validation.
Call
```
assert(condition[, message]);
```
Parameters
- condition: Condition variable.
- message: Optional. Throwing an exception message when it fails.

Example

 assert(1===1, "Not valid");
/*
  Authority: Read-only
  return, Successfully->true; failed->exceptions  
*/

getBalance

Description

getBalance function for getting account information (except metadata and assets).
Call
```
getBalance(address);
```
Parameters
- address: Address of the account.

Example

let balance = getBalance('buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY');
/*
  Authority: Read-Only 
  return, numbers in stype string '999911110000'
*/

storageStore

Description

storageStore function for storing metadata of contract account.

Call

storageStore(metadata_key, metadata_value);

Parameters
- metadata_key: Key of metadata.
- metadata_value: Value of metadata.

Example

storageStore('abc', 'values');
/*
  Authority: Writable 
  return, Successfully->true; failed->exceptions
*/

storageLoad

Description

storageLoad function for getting metadata of contract account.
Call
```
storageLoad(metadata_key);
```
Parameters
- metadata_key: Key of metadata.

Example

let value = storageLoad('abc');
/*
  Authority: Read-Only
  return, Successfully->value in type string; failed->exceptions
*/

storageDel

Description

storageDel function for Deleting metadata of contract account
Call
```
storageDel(metadata_key);
```
Parameters
- metadata_key: Key of metadata.

Example

storageDel('abc');
/*
  Authority: Writable
  return, Successfully->true; failed->exceptions
*/

getAccountAsset

Description

getAccountAsset function for obtaining assets information of an account.

Call

getAccountAsset(account_address, asset_key);

Parameters
- account_address: Address of the account.
- asset_key: Property of the assets.

Example

let asset_key =
{
'issuer' : 'buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY',
'code' : 'CNY'
};
let bar = getAccountAsset('buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY',
asset_key);
/*
  Authority: Read-Only
  return, Successfully->assets amount, such as '10000'; failed->exceptions
*/

getBlockHash

Description

getBlockHash function for getting block information.
Call
```
getBlockHash(offset_seq);
```
Parameters
- offset_seq: Offset from the latest block,range [0,1024).

Example

let ledger = getBlockHash(4);
/*
  Authority: Read-Only
  return, Successfully->value in type string, such as 'c2f6892eb934d56076a49f8b01aeb3f635df3d51aaed04ca521da3494451afb3'; failed->false
*/

addressCheck

Description

addressCheck function for checking the validity of the address.
Call
```
addressCheck(address);
```
Parameters
- address: Address name in type string.

Example

let ret = addressCheck('buQgmhhxLwhdUvcWijzxumUHaNqZtJpWvNsf');
/*
  Authority: Read-Only
  return, Successfully->true; failed->false
*/

stoI64Check

Description

stoI64Check for checking the validity of string number.
Call
```
stoI64Check(strNumber);
```
Parameters
- strNumber: String number in type string.

Example

let ret = stoI64Check('12345678912345');
/*
  Authority: Read-Only
  return, Successfully->true; failed->false
*/

int64Add

Description

int64Add function for addition in 64 bits.
Call
```
int64Add(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Add('12345678912345', 1);
/*
  Authority: Read-Only
  return, Successfully->value in type string, such as'12345678912346'; failed->exceptions
*/

int64Sub

Description

int64Sub function for subtraction in 64 bits.
Call
```
int64Sub(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Sub('12345678912345', 1);
/*
  Authority: Read-Only
  return, Successfully->value in type string, such as'12345678912344'; failed->exceptions
*/

int64Mul

Description

int64Mul function for multiplication in 64 bite.
Call
```
int64Mul(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Mul('12345678912345', 2);
/*
  Authority: Read-Only
  return, Successfully->value in type string as '24691357824690'; failed->exceptions
*/

int64Div

Description

int64Div function for division in 64 bits.
Call
```
int64Div(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Div('12345678912345', 2);
/*
  Authority: Read-Only
  return, Successfully->value in type string as'6172839456172'; failed->exceptions
*/

int64Mod

Description

int64Mod function modulus in 64 bits.
Call
```
int64Mod(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Mod('12345678912345', 2);
/*
  Authority: Read-Only
  return, Successfully->value in type string, such as'1'; failed->exceptions
*/

int64Compare

Description

int64Compare function for comparison in 64bits.
Call
```
int64Compare(left_value, right_value);
```
Parameters
- left_value: Left value.
- right_value: Right value.

Example

let ret = int64Compare('12345678912345', 2);
/*
  Authority: Read-Only
  return, Successfully-> 1(left is larger than right), 0 (equal), -1 (smaller); failed->exceptions
*/

toBaseUnit

Description

toBaseUnit function for switching units.
Call
```
toBaseUnit(value);
```
Parameters
- value: Only accept string number( including the number with point down to the eighth decimal point).

Example

let ret = toBaseUnit('12345678912');
/*
  Authority: Read-Only
  return, Successfully->value in type string as'1234567891200000000'; failed->exceptions
*/

log

Description

log function for log.
Call
```
log(info);
```
Parameters
- info: Log contents.

Example

let ret = log('buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY');
/*
Authority: Read-Only
return, Successfully->null; failed->false
*/

tlog

Description tlog function for recording a transaction on the block.
Call
```
tlog(topic,args...);
```
Parameters
- topic: Log topic, type string, length(0,128].
- args...: At most 5 parameters; type can be string, value, or boolean; length(0,1024].

Example

tlog('transfer',sender +' transfer 1000',true);
/*
  Authority: Writable
  return, Successfully->true; failed->exceptions
*/

issueAsset

Description issueAsset function for issuing assets.
Call
```
issueAsset(code, amount);
```
Parameters
- code: Codes of assets.
- amount: Amount of assets.

Example

issueAsset("CNY", "10000");
/*
  Authority: Writable
  return, Successfully->true; failed->exceptions 
*/

payAsset

Description

payAsset function for transferring assets.

Call

payAsset(address, issuer, code, amount[, input]);

Parameters
- address: Address of the receiver account.
- issuer: Assets issuer.
- code: Codes of assets.
- amount: Asset amount to be transferred.
- input: Optional; defaults to null.

Example

payAsset("buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY",
"buQgmhhxLwhdUvcWijzxumUHaNqZtJpWvNsf", "CNY", "10000", "{}");
/*
  Authority: Writable
  return, Successfully->true; failed->exceptions   
*/

payCoin

Description

payCoin function for Transferring BU coin.
Call
```
payCoin(address, amount[, input]);
```
Parameters
- address: Address of BU receiver account.
- amount: BU amount.
- input: Optional; defaults to null.

Example

payCoin("buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY", "10000", "{}");
/*
  Authority: Writable
  return, Successfully->true; failed->exceptions  
*/

Default Variables

This section describes some default variables involved in the development process of smart contract, including thisAddress、 thisPayCoinAmount、 thisPayAsset、 blockNumber、 blockTimestamp、 sender、 triggerIndex.

thisAddress

Description

Global variable thisAdress is the address of this contract account.
Example

If account X submits a transaction to call contract Y, thisAddressis Y's address:
```
let bar = thisAddress;
  /*
  bar is Y's address.
*/
```

thisPayCoinAmount

Description

BU coin for current operation

thisPayAsset

Description

Asset object for this operation, such as follow:

{
    "amount": 1000, 
    "key": {
        "issuer": "buQsZNDpqHJZ4g5hz47CqVMk5154w1bHKsHY", 
        "code":"CNY"
    }
}

blockNumber

Description

Current block height.

blockTimestamp

Description

Current block timestamp.

sender

Description

Address of the caller (call the function/variables).
Example

There is an operation (from address X) to call contract Y in a transaction. In this process, address X is the sender.
```
let bar = sender;
  /*
  bar is the account address of X.
*/
```

triggerIndex

Description Operation sequence for triggering the contract.
Example

An account A submits a transaction tx0, and the 0-th (count from 0) operation is transferring assets to a contract account (calling the contract). Then triggerIndex is 0.
```
let bar = triggerIndex;
  /*
  bar is an int
*/
```

Exceptions

JavaScript exceptions

While there is an uncaught JavaScript exception in contract operation:
1. Failed execution, all transactions in this contract operation are failed.
2. The transaction triggrted (TRIGGERED) the contract is failed with error code151.
Failure in executing transactions

Contracts can execute several transactions, but only one fault would lead to failure of all transactions and throw exceptions.

Documentation

1.3.1

Introduction to BUMO smart contract

Definition

Global Functions and Default Variables

Global Functions

Read/Write Rights of functions

Return

Details

assert

getBalance

storageStore

storageLoad

storageDel

getAccountAsset

getBlockHash

addressCheck

stoI64Check

int64Add

int64Sub

int64Mul

int64Div

int64Mod

int64Compare

toBaseUnit

log

tlog

issueAsset

payAsset

payCoin

Default Variables

thisAddress

thisPayCoinAmount

thisPayAsset

blockNumber

blockTimestamp

sender

triggerIndex

Exceptions