StabilaBox v2.7.24

Simple development framework for stabilaweb StabilaBox is a fork of Truffle code

StabilaBox Documentation

Installation

npm install -g stabilabox

OS requirement

• NodeJS 8.0+
• Windows, Linux, or Mac OS X

Quick Usage

Initialize a Customer Stabila-Box Project

stabilabox init

Download a dApp, ex: metacoin-box

stabilabox unbox metacoin

Contract Compiler

stabilabox compile

To compile for all contracts, select --compile-all.

Optionally, you can select: --compile-all: Force compile all contracts. --network save results to a specific host network

Configuration

To use StabilaBox, your dApp has to have a file stabilabox.js in the source root. This special files, tells StabilaBox how to connect to nodes and event server, and passes some special parameters, like the default private key. This is an example of stabilabox.js:

module.exports = {
  networks: {
    development: {
      // For stabilatools/quickstart docker image
      privateKey: 'da146374a75310b9666e834ee4ad0866d6f4035967bfc76217c5a495fff9f0d0',
      userFeePercentage: 30, // or consume_user_resource_percent
      feeLimit: 100000000, // or fee_limit
      originUcrLimit: 1e8, // or origin_ucr_limit
      callValue: 0, // or call_value
      fullNode: "http://127.0.0.1:8090",
      solidityNode: "http://127.0.0.1:8091",
      eventServer: "http://127.0.0.1:8092",
      network_id: "*"
    },
    mainnet: {
      // Don't put your private key here, pass it using an env variable, like:
      // PK=da146374a75310b9666e834ee4ad0866d6f4035967bfc76217c5a495fff9f0d0 stabilabox migrate --network mainnet
      privateKey: process.env.PK,
      userFeePercentage: 30,
      feeLimit: 100000000,
      fullNode: "https://api.stabilapi.io",
      solidityNode: "https://api.stabilapi.io",
      eventServer: "https://api.stabilapi.io",
      network_id: "*"
    }
  }
};

Starting from StabilaBox 2.1.9, if you are connecting to the same host for full and solidity nodes, and event server, you can set just fullHost:

module.exports = {
  networks: {
    development: {
      // For stabilatools/quickstart docker image
      privateKey: 'da146374a75310b9666e834ee4ad0866d6f4035967bfc76217c5a495fff9f0d0',
      userFeePercentage: 30,
      feeLimit: 100000000,
      fullHost: "http://127.0.0.1:9090",
      network_id: "*"
    },
    mainnet: {
      // Don't put your private key here, pass it using an env variable, like:
      // PK=da146374a75310b9666e834ee4ad0866d6f4035967bfc76217c5a495fff9f0d0 stabilabox migrate --network mainnet
      privateKey: process.env.PK,
      userFeePercentage: 30,
      feeLimit: 100000000,
      fullHost: "https://api.stabilapi.io",
      network_id: "*"
    }
  }
};

Notice that the example above uses Stabila Quickstart >= 1.1.16, which exposes a mononode on port 9090.

Configure Solc

You can configure the solc compiler as the following example in stabilabox.js

module.exports = {
  networks: {
    // ...
    compilers: {
      solc: {
        version: '0.6.0' // for compiler version
      }
    }
  },

  // solc compiler optimize
  solc: {
    optimizer: {
      enabled: false, // default: false, true: enable solc optimize
      runs: 200
    },
    evmVersion: 'istanbul'
  }
}

Stabila Solidity supported the following versions:

0.4.24
0.4.25
0.5.4
0.5.8
0.5.9
0.5.10
0.5.12
0.5.13
0.5.14
0.5.15
0.5.16
0.5.17
0.5.18
0.6.0
0.6.2
0.6.8
0.6.12
0.6.13
0.7.0
0.7.6
0.7.7
0.8.0
0.8.6

more versions details: https://github.com/stabilaprotocol/solidity/releases

Contract Migration

stabilabox migrate

This command will invoke all migration scripts within the migrations directory. If your previous migration was successful, stabilabox migrate will invoke a newly created migration. If there is no new migration script, this command will have no operational effect. Instead, you can use the option --reset to restart the migration script.

stabilabox migrate --reset

Parameters by contract (introduced in v2.2.2)

It is very important to set the deploying parameters for any contract. In StabilaBox 2.2.2+ you can do it modifying the file

migrations/2_deploy_contracts.js

and specifying the parameters you need like in the following example:

var ConvertLib = artifacts.require("./ConvertLib.sol");
var MetaCoin = artifacts.require("./MetaCoin.sol");

module.exports = function(deployer) {
  deployer.deploy(ConvertLib);
  deployer.link(ConvertLib, MetaCoin);
  deployer.deploy(MetaCoin, 10000, {
    fee_limit: 1.1e8,
    userFeePercentage: 31,
    originUcrLimit: 1.1e8
  });
};

Start Console

This will use the default network to start a console. It will automatically connect to a SVM client. You can use --network to change this.

stabilabox console

The console supports the stabilabox command. For example, you can invoke migrate --reset in the console. The result is the same as invoking stabilabox migrate --reset in the command.

Extra Features in StabilaBox console:

1. All the compiled contracts can be used, just like in development & test, front-end code, or during script migration.

2. After each command, your contract will be re-loaded. After invoking the migrate --reset command, you can immediately use the new address and binary.

3. Every returned command's promise will automatically be logged. There is no need to use then(), which simplifies the command.

Testing

To carry out the test, run the following command:

stabilabox test

You can also run the test for a specific file：

stabilabox test ./path/to/test/file.js

Testing in StabilaBox is a bit different than in Truffle. Let's say we want to test the contract Metacoin (from the Metacoin Box that you can download with stabilabox unbox metacoin):

contract MetaCoin {
	mapping (address => uint) balances;

	event Transfer(address _from, address _to, uint256 _value);
	event Log(string s);

	constructor() public {
		balances[tx.origin] = 10000;
	}

	function sendCoin(address receiver, uint amount) public returns(bool sufficient) {
		if (balances[msg.sender] < amount) return false;
		balances[msg.sender] -= amount;
		balances[receiver] += amount;
		emit Transfer(msg.sender, receiver, amount);
		return true;
	}

	function getBalanceInEth(address addr) public view returns(uint){
		return ConvertLib.convert(getBalance(addr),2);
	}

	function getBalance(address addr) public view returns(uint) {
		return balances[addr];
	}
}

Now, take a look at the first test in test/metacoin.js:

var MetaCoin = artifacts.require("./MetaCoin.sol");
contract('MetaCoin', function(accounts) {
  it("should put 10000 MetaCoin in the first account", function() {

    return MetaCoin.deployed().then(function(instance) {
      return instance.call('getBalance',[accounts[0]]);
    }).then(function(balance) {
      assert.equal(balance.toNumber(), 10000, "10000 wasn't in the first account");
    });
  });
  // ...

Starting from version 2.0.5, in StabilaBox artifacts () the following commands are equivalent:

instance.call('getBalance', accounts[0]);
instance.getBalance(accounts[0]);
instance.getBalance.call(accounts[0]);

and you can pass the address and amount for the method in both the following ways:

instance.sendCoin(address, amount, {from: account[1]});

and

instance.sendCoin([address, amount], {from: account[1]});

Verifying the PGP signature

Prepare, you need to install the npm pkgsign for verifying.

First, get the version of stabilabox dist.tarball

$ npm view stabilabox dist.tarball
https://registry.npmjs.org/stabilabox/-/stabilabox-2.7.24.tgz

Second, get the tarball

wget https://registry.npmjs.org/stabilabox/-/stabilabox-2.7.24.tgz

Finally, verify the tarball

$ pkgsign verify stabilabox-2.7.24.tgz --package-name stabilabox
extracting unsigned tarball...
building file list...
verifying package...
package is trusted

You can find the signature public key here.

How to contribute

1. Fork this repo.

2. Clone your forked repo recursively, to include submodules, for example:

git clone --recurse-submodules -j8 [email protected]:stabilaprotocol/stabilabox.git

3. If you use nvm for Node, please install Node 8, and install lerna globally:

nvm install v8.16.0
nvm use v8.16.0
npm i -g lerna

4. Bootstrap the project:

lerna bootstrap

5. During the development, for better debugging, you can run the unbuilt version of StabilaBox, for example

./stabilabox.dev migrate --reset

StabilaBox Changelog

for more details: CHANGELOG