MyBit Network - Contract SDK

🏭 A software development kit for the automated machine economy.

Network SDK's are a protocol that allows the creation of decentralised digital assets, funding and trading. It also enables the distribution of revenue generated by assets. These SDK's contain all the functional logic of MyBit-Go.

For a simple example see Hello-Network
For importing the SDK's as an NPM package see Network.js

Getting Started

First install dependencies using Yarn:

yarn

If successful you should see output similar to below:

[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
Done in 5.69s.

Then get a local test blockchain running using Ganache

yarn blockchain

In another terminal window, you can now run the tests:

yarn tests

To see code-coverage run:

yarn coverage

Roles

The MYB SDK's have 4 fundamental roles:

Investor must burn MYB to participate
AssetManager must burn MYB to participate
Operator must be registered by owners
Platform Owner(s)

Investors can contribute ETH or Erc20 tokens to invest in new asset crowdsales. The assets are managed by the AssetManager, who receives a fee for his work and escrows tokens as collateral to investors. The Operator receives funds from the crowdsale and produces and install the asset. Platform owners can choose how assets are governed, and whether or not a contract upgrade should happen. The platform owner can be a single account or a contract governed by many accounts.

Setting Up The Platform

Before creating assets, certain variables and parameters have to be set:

All contracts must be registered in ContractManager before writing to database
All users must approve the current contract state, which changes everytime a contract is added/updated
Users must approve ERC20Burner to burn platform tokens before using key functionality
Platform wallet and platform token must be set
Operators must be registered and choose which currencies they wish to accept

Basic functionality for these critical operations are outlined below. All contracts are found here

Database

Contracts in the SDK store all long-term data in a database contract, which allows for contracts to be upgraded without losing valuable data. The Database stores all data using a bytes32 type, which is often the keccak256 hash of the variableName, ID, address that make up that variable.

Storing an unsigned integer looks like this:

  database.setUint(keccak256(abi.encodePacked("fundingDeadline", assetID)), 20000000);

The Database stores this with key = sha3("fundingDeadline", assetID) and value = 20000000

function setUint(bytes32 _key, address _value)
onlyApprovedContract
external {
    uintStorage[_key] = _value;
}

API

The API contract can be used to easily fetch variables from the database

  function getAssetFundingDeadline(bytes32 _assetID)
  public
  view
  returns(uint) {
    uint fundingDeadline = database.uintStorage(keccak256(abi.encodePacked("fundingDeadline", _assetID)));
    return fundingDeadline;
  }

ContractManagement

To give a contract write access to the database, you must call addContract(contractName, contractAddress) from a platform owner account

  function addContract(string _name, address _contractAddress)
  external
  isTrue(_contractAddress != address(0))
  isTrue(bytes(_name).length != uint(0))
  anyOwner {
    require(!database.boolStorage(keccak256(abi.encodePacked("contract", _contractAddress))));
    require(database.addressStorage(keccak256(abi.encodePacked("contract", _name))) == address(0));
    database.setAddress(keccak256(abi.encodePacked("contract", _name)), _contractAddress);
    database.setBool(keccak256(abi.encodePacked("contract", _contractAddress)), true);
    bytes32 currentState = database.bytes32Storage(keccak256(abi.encodePacked("currentState")));    
    bytes32 newState = keccak256(abi.encodePacked(currentState, _contractAddress));
    database.setBytes32(keccak256(abi.encodePacked("currentState")), newState);
    emit LogContractAdded(_contractAddress, _name, block.number);
  }

Everytime a contract is added or updated the contract state will change, requiring approval from users before they interact with the platform. Users can also choose to ignore future state changes. This can be done by calling the following function:

  function setContractStatePreferences(bool _acceptCurrentState, bool _ignoreStateChanges)
  external
  returns (bool) {
    bytes32 currentState = database.bytes32Storage(keccak256(abi.encodePacked("currentState")));
    database.setBool(keccak256(abi.encodePacked(currentState, msg.sender)), _acceptCurrentState);
    database.setBool(keccak256(abi.encodePacked("ignoreStateChanges", msg.sender)), _ignoreStateChanges);
    emit LogContractStatePreferenceChanged(msg.sender, _acceptCurrentState, _ignoreStateChanges);
    return true;
  }

TokenBurning

To create new asset orders, or purchase existing asset orders, users must provably burn MYB using the burner. To do this each user must approve the burner contract to burn tokens by calling the MYB contract:

  function approve(address _spender, uint256 _value) public returns (bool) {
    allowed[msg.sender][_spender] = _value;
    emit Approval(msg.sender, _spender, _value);
    return true;
  }

spender in this case should be the address of the ERC20Burner contract. value should be placed high enough to avoid needing to approve the burner every use

Tokens are burnt before the function runs due to the modifier burnRequired which calls burn() at the burner contract:

  function burn(address _tokenHolder, uint _amount)
  external
  onlyPlatformContracts(msg.sender)
  acceptedState(_tokenHolder)
  returns (bool) {
    require(token.burnFrom(_tokenHolder, _amount));
    emit LogMYBBurned(_tokenHolder, msg.sender, _amount);
    return true;
  }

Functions that require burning:

CrowdsaleGeneratorETH.createAssetOrderETH()
CrowdsaleETH.buyAssetOrderETH()
CrowdsaleGeneratorERC20.createAssetOrderERC20()
CrowdsaleERC20.buyAssetOrderERC20()
AssetExchange.buyAsset()
AssetExchange.createBuyOrder()

Platform-Variables

Before assets can be funded the platform owners must set the platform token and the platform wallet by using:

  function setPlatformWallet(address _walletAddress)
  external
  onlyOwner {
    database.setAddress(keccak256(abi.encodePacked("platformWallet")), _walletAddress);
    emit LogPlatformWallet(_walletAddress);
  }

➕

  // @notice
  function setPlatformToken(address _tokenAddress)
  external
  onlyOwner {
    database.setAddress(keccak256(abi.encodePacked("platformToken")), _tokenAddress);
    emit LogPlatformToken(_tokenAddress);
  }

Onboarding Operators

The Operator must be registered and define what currencies they are willing to receive as payment. To set the operators you can call:

function registerOperator(address _operatorAddress, string _operatorURI)
external
onlyOwner {
  require(_operatorAddress != address(0));
  bytes32 operatorID = keccak256(abi.encodePacked(_operatorURI));
  require(database.addressStorage(keccak256(abi.encodePacked("operator", operatorID))) == address(0));
  database.setAddress(keccak256(abi.encodePacked("operator", operatorID)), _operatorAddress);
  database.setBytes32(keccak256(abi.encodePacked("operator", _operatorAddress)), operatorID);
  emit LogOperatorRegistered(operatorID, _operatorURI);
}

To choose which currencies the operator would like to accept they can call:

function acceptERC20Token(bytes32 _operatorID, address _tokenAddress, bool _accept)
external
onlyOperator(_operatorID)
returns (bool) {
  database.setBool(keccak256(abi.encodePacked("acceptsToken", _operatorID, _tokenAddress)), _accept);
  return true;
}

OR

function acceptEther(bytes32 _operatorID, bool _accept)
external
onlyOperator(_operatorID)
returns (bool) {
  database.setBool(keccak256(abi.encodePacked("acceptsEther", _operatorID)), _accept);
  return true;
}

❗ The Operator can choose to accept Ether and an unlimited number of ERC20 tokens if they want.

Creating Assets

To create assets you will use CrowdsaleGeneratorETH or CrowdsaleGeneratorERC20

For Ether based crowdsales you would call createAssetOrderETH() from the AssetManager account, effectively creating a new crowdsale

  function createAssetOrderETH(string _assetURI, bytes32 _operatorID, uint _fundingLength, uint _amountToRaise, uint _assetManagerPerc)
  external
  burnRequired
  returns (bool) {
    require(_amountToRaise > 0);
    require(_assetManagerPerc < 100);
    require(database.boolStorage(keccak256(abi.encodePacked("acceptsEther", _operatorID))));
    require(database.addressStorage(keccak256(abi.encodePacked("operator", _operatorID))) != address(0));
    bytes32 assetID = keccak256(abi.encodePacked(msg.sender, _amountToRaise, _operatorID, _assetURI));
    require(database.uintStorage(keccak256(abi.encodePacked("fundingDeadline", assetID))) == 0);
    address assetAddress = address(new DividendToken(_assetURI, database.addressStorage(keccak256(abi.encodePacked("contract", "CrowdsaleETH")))));   // Gives this contract all new asset tokens
    database.setUint(keccak256(abi.encodePacked("fundingDeadline", assetID)), now.add(_fundingLength));
    uint assetManagerFee = _amountToRaise.mul(uint(100).mul(scalingFactor).div(uint(100).sub(_assetManagerPerc)).sub(scalingFactor)).div(scalingFactor);
    database.setUint(keccak256(abi.encodePacked("assetManagerFee", assetID)), assetManagerFee);
    database.setUint(keccak256(abi.encodePacked("amountToRaise", assetID)), _amountToRaise);
    database.setAddress(keccak256(abi.encodePacked("tokenAddress", assetID)), assetAddress);
    database.setBytes32(keccak256(abi.encodePacked("assetTokenID", assetAddress)), assetID);
    database.setAddress(keccak256(abi.encodePacked("assetManager", assetID)), msg.sender);
    database.setAddress(keccak256(abi.encodePacked("operator", assetID)), database.addressStorage(keccak256(abi.encodePacked("operator", _operatorID))));
    emit LogAssetFundingStarted(assetID, msg.sender, _assetURI, address(assetAddress));
    return true;
  }

Funding Assets

To fund an asset you can use either CrowdsaleETH or CrowdsaleERC20

For Ether based crowdsales you would call buyAssetOrderETH() from the investor account:

  function buyAssetOrderETH(bytes32 _assetID)
  external
  payable
  requiresEther
  validAsset(_assetID)
  beforeDeadline(_assetID)
  notFinalized(_assetID)
  burnRequired
  returns (bool) {
    EtherDividendInterface assetToken = EtherDividendInterface(database.addressStorage(keccak256(abi.encodePacked("tokenAddress", _assetID))));
    uint amountToRaise = database.uintStorage(keccak256(abi.encodePacked("amountToRaise", _assetID)));
    uint tokensRemaining = amountToRaise.sub(assetToken.totalSupply());
    if (msg.value >= tokensRemaining) {
      // Give assetManager his portion of tokens
      require(assetToken.mint(database.addressStorage(keccak256(abi.encodePacked("assetManager", _assetID))), database.uintStorage(keccak256(abi.encodePacked("assetManagerFee", _assetID)))));
      require(finalizeCrowdsale(_assetID));    // delete unnecessary variables
      require(assetToken.mint(msg.sender, tokensRemaining));   // Send remaining asset tokens
      require(assetToken.finishMinting());
      require(payoutETH(_assetID, amountToRaise));          // 1 token = 1 wei
      msg.sender.transfer(msg.value.sub(tokensRemaining));     // Return leftover WEI after cost of tokens calculated and subtracted from msg.value
    }
    else {
      require(assetToken.mint(msg.sender, msg.value));
    }
    emit LogAssetPurchased(_assetID, msg.sender, msg.value);
    return true;
}

If the funding fails you can call refund() , which sends all funds to the asset-token contract to be redistributed to investors

Distributing Revenue

By default all assets generated on the platform are able to receive payments and distribute revenue equally to token holders. It accomplishes this by keeping track of how much value (WEI/Token) is contained in each asset-token. The token contract can receive payment in it's fallback function or by calling issueDividends()

Investors an withdraw income by calling withdraw() which updates their personal ledger:

  function withdraw()
  public
  updateIncomeClaimed(msg.sender)
  returns (bool) {
      uint amount = incomeOwed[msg.sender].div(scalingFactor);
      delete incomeOwed[msg.sender];
      emit LogIncomeCollected(msg.sender, amount);
      msg.sender.transfer(amount);
      return true;
  }

In-Development

🚧 The SDK's are a work in progress and we hope to implement more features such as asset-governance, platform-governance and obfuscated asset authentication.

Governance

We are working on giving investors governance tools to vote for new AssetManagers if the need arises. Voting is based on token holdings and can be accomplished by approving a function call at a particular contract:

  function voteForExecution(address _executingContract, bytes32 _assetID, bytes4 _methodID, bytes32 _parameterHash, uint _amountToLock)
  external
  validAsset(_assetID)
  returns (bool) {
    bytes32 executionID = keccak256(abi.encodePacked(_executingContract, _assetID, _methodID, _parameterHash));
    bytes32 numVotesID = keccak256(abi.encodePacked("voteTotal", executionID));
    bytes32 investorVotesID = keccak256(abi.encodePacked("investorVotes", executionID, msg.sender));
    uint256 numVotes = database.uintStorage(numVotesID);
    uint256 investorVotes = database.uintStorage(investorVotesID);
    require(lockTokens(_assetID, msg.sender, _amountToLock));
    database.setUint(numVotesID, numVotes.add(_amountToLock));
    database.setUint(investorVotesID, investorVotes.add(_amountToLock));
    return true;
  }

executingContract = The address of the contract, where the function is to be called
assetID = The ID of the asset in question
methodID = The function signature of the funtion to be called ie. bytes4(sha3("exampleFunction(address, uint256, bool)"))
parameterHash = The sha3 hash of the exact parameters to be called at that function
amountToLock - The number of asset-tokens this investor wishes to lock towards this function call

✏️ All contracts are written in Solidity version 0.4.24.

Documentation

Documentation is created using Solidity-Docgen

cd docs/website
yarn build

To publish to GitHub Pages

cd docs/website
GIT_USER=<GIT_USER> \
  USE_SSH=true \
  yarn run publish-gh-pages

Live example test-net contracts

⚠️ This application is unstable and has not undergone any rigorous security audits. Use at your own risk.

MyBit Platform™ CHE-177.186.963

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

MyBit Network - Contract SDK

Getting Started

Roles

Setting Up The Platform

Database

API

ContractManagement

TokenBurning

Platform-Variables

Onboarding Operators

Creating Assets

Funding Assets

Distributing Revenue

In-Development

Governance

Documentation

Live example test-net contracts

Files

README.md

Latest commit

History

README.md

File metadata and controls

MyBit Network - Contract SDK

Getting Started

Setting Up The Platform

Creating Assets

Funding Assets

Distributing Revenue

In-Development

Documentation

Live example test-net contracts