modular-network / ethereum-libraries

Library contracts for Ethereum

Modular Libraries

Modular Libraries is a group of packages built for use on blockchains utilizing the Ethereum Virtual Machine (EVM). All libraries are deployed and linkable in your smart contracts on both Rinkeby, Ropsten, and Ethereum Mainnet. We also have an ethereum-contracts repository that currently holds ICO contracts.

Libraries and contracts are currently written in Solidity and Solidity Assembly. If you are not familiar with the workings of Ethereum, smart contracts, or Solidity please educate yourself by clicking here before proceeding.

If you want to contribute to the libraries or just join the discussion on smart contract development and security, please join our Discord at https://discordapp.com/invite/crxYSF2

• Why Modular Libraries?
• How to use
• How to Contribute
  • Feedback and Bug Reports
  • Collaborations
  • Code Contributions
  • Code Quality
• Why Libraries?
• In Conclusion

Why Modular Libraries?

Modular Libraries aims to supplement current projects such as Open-Zeppelin and others by utilizing the facilities Ethereum has in place to provide reusable source code on-chain. Our library code has been tested, documented, and deployed with the purpose of being used in Ethereum smart contracts. Be sure to familiarize yourself with libraries as well as the benefits and drawbacks to ensure you pick solutions that best fits your needs.

DISCLAIMER

While we make every effort to write, review, secure, test, and document professional grade code, all code is released open source under the MIT license and "without warranty of any kind." We shall not be held liable for any damages or lost funds so please be careful and prudent with your implementation. Please review and familiarize yourself with the entire license and accompanying disclaimers.

DISCLAIMER

How to use

Modular Libraries has been packaged such that each library is available independently from any other library. You can browse each folder and pick the library or libraries that you need for your smart contracts.

The README in each library contains the Rinkeby, Ropsten, and Mainnet address of the deployed library to link in your contract. You will find documentation for the functions and installation instructions for development and deployment use as well. Additionally, each library has as an ENS domain which is not of much use now but will provide a better experience as development proceeds. All deployed source code has been verified on etherscan.io for your viewing pleasure.

How to Monitor Events Emmitted by Modular Libraries

In docs/LibraryLogHashes.csv, you can find a listing of all of the zero-topic hashes for the events that our libraries emit. You can use these in your web app to monitor events that contracts that use our libraries emit.

How to Contribute

Feedback, bug reports, library submissions, collaborations, and contributions are all welcome! We will be rewarding contributions so please do not hesitate to reach out to us.

Feedback and Bug Reports

If you have feedback about our libraries or questions about our documentation, or find a bug in our code, please contact us as soon as possible at [email protected] or reach out to us on on Gitter or Discord channel. Significant contributions will be rewarded.

Collaborations

As part of the global Ethereum/Blockchain community, we at Modular want to do our part in supporting fellow projects and enthusiasts in the community. If you need an audit, advice, help building a secure ICO or Ethereum Dapp, or any other type of collaboration, please get in touch at [email protected] where we can discuss the collaboration.

Code Contributions

If you see an issue in our repo or a piece of code in our Libraries you want to improve, please don't hesitate to dive in. We welcome help in any form and are more than willing to offer our assistance to developers who want to contribute to documentation, code fixes, or even new libraries or functionality! We ask that you follow a few guidelines when making changes to the repo:

1. Create a branch separate from master for any changes.
2. Create separate branches and submissions for unrelated changes.
3. Please adhere to Ethereum Natural Specification Format Guidelines for function documentation. Also, leave comments on functional blocks in the code so that any functionality is easy to understand by any moderately competent developer reading the code.
4. If you are making significant changes, include a README with function signatures, inputs, outputs, and a detailed description of the functionality.
5. Include the description of the changes on the Pull Request.
6. When creating a pull request on the main repo, do not submit it to master. Either submit it to an existing branch that was allocated for the changes, or submit it to a new branch you create with the PR.

Code Quality

We strive to maintain high standards at Modular. To accomplish this, we have included unit tests and a coverage report tool. We are using the solitidy-coverage tool and Codecov to host our reports and analysis. Let's keep growing our coverage percentage as much as we can!

Why Libraries?

Utilizing libraries has some of the following benefits:

• Reduce deployment costs

  The overall bytecode load you deploy for your own contracts is reduced because your contract will not contain the function used from a linked library's external function. Your contract will make external calls to a linked library.

• Provide reliability

  Common libraries and reusable source code naturally receive higher visibility and scrutiny. This provides better code for developers as well as a known location to report and review bugs after many use cases.

• Improve security

  Libraries help to improve the security of your code because of the same circumstances that provide reliability. With that said please review the license and disclaimer before use.

Utilizing libraries has some of the following drawbacks:

• Increase execution costs

  Using external calls to library functions on-chain causes some overhead that does not exist when using internal functions. So, while contract deployments are less expensive, contract gas usage increases with execution. If this is a concern and you have a higher need to reduce gas usage upon execution than to reduce gas usage upon deployment, you can modify the contract function with an internal modifier. This will pull the function into your contract when you deploy. Please review the Solidity docs on libraries if you are not familiar with this.

• Deployed libraries are immutable

  This is a concern more for our approach rather than the approach other repositories use. Since our focus is on deployed libraries, the code at this address is as permanent as the blockchain. Don't hold your breath for changes. There are some upsides in that immutable code is guaranteed to never have a breaking change so you can rely on it for as long as it is relevant. There are initiatives we've seen, particularly with Aragon and OpenZepplein, that plan on making library code upgradable to a certain extent. We will keep an eye on these developments as well as continue our plans to help develop a versioning system on-chain.

• Understanding someone else's code

  For the same reason libraries give us the benefit of reusable community code, it requires us to understand someone else's logic. Again, we strive for excellence, but sometimes it may not be the best implementation. Such as when we have used Solidity Assembly to improve our own competence in the language, the same thing could be done just as efficiently in basic Solidity. Our approach to this downside is to ensure we verify the deployed code and provide adequate documentation.

In Conclusion

As always you should stay informed and determine what works best for you and your project. We look forward to working with everyone and we welcome anyone that wants to collaborate. [Please visit modular.network](https://modular.network"Modular website") to see more information about us and opportunities.

ethereum-libraries's Issues

Derivate compiler output and duplicate files in source repo

What is it?

You've got the outputs from the truffle compile in the (source code) repo. That's an anti-pattern.

Problem

Keep source code in the repo.
Along with notes and settings and your package.json if needed so a dev can recreate the outputs.

Put your outputs in a release package, like npm or similar (truffle offers a packaging tool).

Don't keep duplicates of your source files in the same repo. Refactor. DRY (don't repeat yourself), etc.

Basically, this is not the recommended way to use a code repo.

Solution

Delete derivate files and re-commit and push.

Steps to implement

1. Provide either a numbered list
2. That that provides steps to implement

• Or a bullet list of items
• If order doesn't matter

Build ERC-721 Library

What is it?

ERC-721: Non fungible token library

Problem

We want to have a non-fungible token option in our libraries.

Solution

Build a library similar to TokenLib that implements functionality described in the erc-721 standard

Steps to implement

References:

• https://medium.com/crypto-currently/the-anatomy-of-erc721-e9db77abfc24
• ethereum/EIPs#721

Refactoring test data creation for Array Libraries

In the array library, a set of test data is created for each test case. This creates a lot of unnecessary code.

Simply create a function that automates the creation of test data that can be used by each test case

Review/Document/Add more test cases to LinkedListLib

Right now, the Linked List library is functional and has some test cases, but more discussion needs to be had on what kind of return values different functions should have to help with ease of use. We also need more code coverage on our test suite for the Linked list.

Tasks:

• Speak with Josh about suggestions for return codes

• Add more test cases

Remove Crowdsale Raise Caps

What is it?

None of the sale contracts need an explicit raise cap, they are capped by the tokens in the sale.

Problem

The raise cap is unneccessary

Solution

Remove the raise cap for all sale contract.

Add Hard cap functionality to sale

What is it?

Sales need an option for a hard cap to be used to end the sale when it is reached.

Problem

Right now, we have a raise cap, but it only stops purchases. It does not end the sale completely.

Solution

Add functionality to allow users to end the sale if the hard cap is reached

Steps to implement

1. Modify CrowdsaleLib.sol to add this functionality
2. Test intended behavior to ensure that functionality is correct.

standardize modular

What is it?

We need to change all instances of majoolr to modular

Problem

Our name is Modular now so Majoolr needs to go die

Solution

find all the instances of majoolr in the libraries and change them to their appropriate title.

Steps to implement

• Majoolr Inc changes to Modular Inc
• https://github.com/Majoolr/ changes to https://github.com/Modular-Network/
• majoolr.io changes to modular.network
• and mentions of majoolr or Majoolr change to modular or Modular

any other examples I don't mention should be self-explanitory. just do a:
grep -ri majoolr *
in different directories to find all the instances of majoolr and ERADICATE THEM

LinkedList npm package with hard pragma

What is it?

Since the pragma in the npm package LinkedList is hard restricted to version 0.4.21 it is not possible to reuse the library in a useful manner.

Problem

The linked library code in this repository has a soft ^0.4.18 version restriction. The code in the npm package however has a hard 0.4.21 restriction. This makes it impossible to simply reuse the library without changes, for example with the current truffle.

Solution

Redeploying the npm package with a soft restriction ^0.4.21 would allow to reuse the code and the on-chain deployed library in current projects without the need for workarounds.

Gas estimation errored

What is it?

Gas estimation errored

Problem

Gas estimation errored with the following message (see below). The transaction execution will likely fail. Do you want to force sending?
Internal JSON-RPC error.

Solution

Describe the solution to the above stated problem.

Steps to implement

using Array256Lib for uint256[];

uint256[] arr_;

`function test(uint256 _testnb)
public
payable
{

    uint256 v_ = msg.value;
    
    numOfaddr_[_testnb] = msg.sender;
    
    
    uint256 _ss = generateRandom();
    
    arr_.push(_ss);
    arr_.heapSort();
    
    emit onALib(arr_.getMax());
    
}`

remix 0.4.24

TokenLib possibly re-initialisable for mintable tokens with zero initial supply

On this line, a check is made that:

require(self.INITIAL_SUPPLY == 0);

It is my understanding that the above check is made as a substitute for a "storage has not been initialised" check. An implicit assumption is made that the token creator won't have an initial supply of 0.

I'm evaluating Majoolr for use in a mintable token where, by design, the initial supply is 0. For such a token, init() is under-protected.

---

If my guess above is correct, I'd propose using a separate bool flag for that, the intent of which is not collated with any other parameter. Something like:

require(self.initialised == false);
...
self.initialised = true;

---

Tangent: although the Solidity style guide suggests using all-caps for constants, it is IMO best reserved for compile-time constants. There is no storage write protection in the EVM (yet, TTBOMK), so the "constant" may be overwritten in storage due to, say, a compiler bug (even if unlikely).

Token Pre-Sale Auto Allocation/Distribution Library

What is it?

Contract to handle pre-sale allocation/distribution

Problem

More and more projects are doing presales and need a way to allocate tokens to parties when transactions are handles offchain. We need a library to solve this.

Solution

Discuss and build standard library for building this

Steps to implement

1. Discuss with the Modular team about what kind of functionality needs to be covered in the library
2. Build library
3. Test and document

Add more tests for StrintUtilsLib

Build Dutch Auction Crowdsale Library

What is it?

We need a library for a Dutch Auction Crowdsale

Problem

We need to flesh out our library of crowdsale models, and a dutch auction library similar to Gnosis or Raiden's models would be good to have.
https://github.com/raiden-network/raiden-token

Solution

Research how dutch auction token sales function and build a library that utilizes the base CrowdsaleLib.sol so achieve dutch auction functionality

Steps to implement

1. Research previous implementations of dutch auction crowdsales
2. Write spec for DutchAuctionCrowdsale.sol including storage structs.
3. Translate spec into library code, following formatting similar to other Modular libraries
4. extensively document and test the implementations
5. Build README documenting the functionality similar to other library READMEs

Owner can withdraw all ETH after the sale has completed

What is it?

When the sale is completed, there will be some participants whose personal valuation cap is below the total sale valuation, who have ETH left in the contract.

The owner can unilaterally withdraw all of this ETH.

Problem

The withdrawOwnerEth() function is used unmodified from the CrowdSaleLib.sol.

https://github.com/ConsenSys/IICO_repo/blob/audits/CrowdsaleLib/IICOLib/truffle/contracts/InteractiveCrowdsaleLib.sol#L647

https://github.com/ConsenSys/IICO_repo/blob/audits/CrowdsaleLib/CrowdsaleLib.sol#L204

In a normal crowdsale, all ETH naturally belongs to the owner. That is not the case in the IICO.

Remove Three Day Crowdsale Requirement

What is it?

The CrowdsaleLib currently enforces sales be launched at least 3 days prior to start time on line 110.

Problem

This shouldn't be enforced at the library level and left to contract creators.

Solution

Remove this requirement.

Steps to implement

• Remove the line
• Update version in the .sol file adding v0.0.+1, also in the README and package.json
• Update line number location for each function after each function in the README

Document/Add more test cases to WalletLib

Right now there are a good amount of test cases for the Wallet Library but it could use more test cases for better code coverage.

• Document our current suite of test in order to determine what test cases we have covered

• Use this information to reveal any states that our tests are not covering

• Include tests that use common solidity exploits to ensure our Wallet is resistant to them.

• Expand the tests to include all of these cases

Speak with Chris or Josh for help on the WalletLibraries or testing framework. We are happy to help. :)

Create npm package

What is it?

We need an npm package for these libraries

Problem

Users would benefit from having a package they can download for these libraries instead of copying

Solution

Build an npm package

Steps to implement

1. I don't know how to do it so
2. I'm looking into this and could use some help

Doc clarification needed

in the README, under the section "Testing the library in truffle" the document states:

1. git clone --recursive or download the truffle directory. Each folder in the truffle directory correlates to the folders in your truffle installation.

huh? running git clone --recursive in my project directory just displays syntax. should that be: git clone --recursive https://github.com/Majoolr/ethereum-libraries?

but then it instructs "or download the truffle directory" -- from where?

Standardize LogErrorMsg throughout all the libraries and contracts

There is some discrepancy between definitions of the event LogErrorMsg among our libraries and contracts. We'll need to go through all of them and make sure that they all have the same signature:

event LogErrorMsg(uint256 amount, string Msg);

Document Gas Costs for all state-changing functions in libraries

What is it?

Document Gas Costs for all state-changing functions in libraries

Problem

We need to know average gas costs for all of the functions in our libraries so we can accurately predict for users of the libraries and platform.

Solution

Run a node on rinkeby and execute scripts that run functions in our libraries with common input parameters as well as edge cases to get minimum/average/max gas costs.

Steps to implement

Sorted by relative order of priority

• BasicMathLib
• TokenLib
• CrowdsaleLib
• DirectCrowdsaleLib
• InteractiveCrowdsaleLib
• ArrayUtilsLib
• EvenDistroCrowdsaleLib
• LinkedListLib
• VestingLib
• WalletLib

BasicMathLib Events

In BasicMathLib.sol, each function is declared as constant but can possibly emit an event. Wouldn't emitting an event modify state - making this not a constant function?

Just wondering :)

Remove Crowdsale Need for Token

What is it?

For the IICO we need to mint tokens out of the sale contract, therefore we need to adjust initilization such that the token is not required

Informal Audits

What is it?

Small suggestions by community members for improvements to library security

Problem

We are very confident in the functionality and security of our libraries, but audits are always welcome.

Solution

If anyone wants to looks through the libraries with a security mindset, go right ahead.

Steps to implement

• refer to Consensys best practices for a reference on security
• Libraries we are especially looking to get eyes on are:
• WalletLib
• CrowdsaleLib
• VestingLib
• EvenDistroCrowdsaleLib

Remove exchange rate conversion

What is it?

Removing inputs being in terms of cents and making them tokensPerEth

Problem

Most sales are ok with stating price in tokens/Eth and therefore we should move in that direction

Solution

Remove price conversion from cents and have inputs be tokens/eth directly

Create additional functionality for Array Libraries

Right now we have functions implemented in the Array Libraries that we are using for our other libraries, but other types of functions could be useful in the future for different types of libraries and applications. Some other functionality can be added based on what is found in other language's standard libraries, like underscore for Javascript. Make sure you add test cases for all the new functionality

Keep in mind that returning dynamic arrays from externally called functions in Solidity will not be implemented until Metropolis, but how awesome would it be if we had functions ready for that when it comes out?

Josh can help with details of the Array Library

BasicMathLib emits events in constant functions

What is it?

Events are recorded as part of the transaction receipt, so emitting events goes somewhat against the notion of "constantness".

Problem

When using TokenLib (which itself uses BasicMathLib) in a contract that needs some experimental v0.5.0 features of Solidity - where constant/view/pure will be checked and/or enforced - a warning is emitted, highlighting the above discrepancy.

This warning may well turn into an error when Solidity v0.5 is released proper. It would be nice to have discussion now as to whether Majoolr's approach needs adjustment.

Proposed solution

Do not emit events from within these functions. This should be up to those using the library - after all, an err indicator is also returned.

Steps to reproduce

1. include BasicMathLib 1.1.0 in a contract;
2. specify `pragma experimental "v0.5.0" for said contract;
3. use solc >= v0.4.18 to compile it;
4. observe warnings:

oobiqoo.sol:5:1: Warning: Experimental features are turned on. Do not use experimental features on live deployments.
pragma experimental "v0.5.0";
^---------------------------^
oobiqoo.sol:37:5: Warning: No visibility specified. Defaulting to "public".
    function oobiqoo(address __owner) {
    ^
Spanning multiple lines.
majoolr/BasicMathLib.sol:49:7: Warning: Function declared as view, but this expression (potentially) modifies the state and thus requires non-payable (the default) or payable.
      Err("times func overflow");
      ^------------------------^
majoolr/BasicMathLib.sol:67:5: Warning: Function declared as view, but this expression (potentially) modifies the state and thus requires non-payable (the default) or payable.
    Err("tried to divide by zero");
    ^----------------------------^
majoolr/BasicMathLib.sol:87:7: Warning: Function declared as view, but this expression (potentially) modifies the state and thus requires non-payable (the default) or payable.
      Err("plus func overflow");
      ^-----------------------^
majoolr/BasicMathLib.sol:106:7: Warning: Function declared as view, but this expression (potentially) modifies the state and thus requires non-payable (the default) or payable.
      Err("minus func underflow");
      ^-------------------------^

Update TokenLib Transfer

Make recommended change in transfer function to check that _to is not 0.

Add function visibility to all library functions

Right now, most of our functions in libraries do not have public, external, or internal modifiers on them. Functions are public by default, but just to ensure security and readability, we should make the visibility of all our library functions explicit.

Tasks:

• Look through functions in all libraries and add modifiers public, external, or internal to each function.
  Most will continue being public, but there might be some functions that need to be internal if they will only ever be called by contract or library functions.

• Run all library tests to ensure that the changes don't break any functionality

• Submit a pull request with additions and confirm with Josh or Chris that modifications are accurate

Add InteractiveCrowdsaleLib

What is it?

Bringing in the InteractiveCrowdsale

Problem

We don't have it yet.

Solution

Bring in a working solution

Steps to implement

• Test in the collaborative group
• Add project into our repo
• Incorporate our own testing

Document Log Hashes for Library Events

What is it?

We need a record of all the log hashes for every event in all the libraries

Problem

In order to be able to access logs easily from web applications, logs need to be able to be retrieved easily by their log hashes.

Solution

Use testrpc to run libraries through all the events they can possibly emit and record the hashes of all the logs.

Steps to implement

every transaction has a list of logs that a transaction initiated.
index 0 of of the topics key is the hash of the event signature.

• TokenLib
• CrowdsaleLib
• DirectCrowdsaleLib
• InteractiveCrowdsaleLib
• EvenDistroCrowdsaleLib
• VestingLib
• ArrayUtilsLib
• WalletLib

Superfluous require guard on WithdrawOwnerEth()

What is it?

CrowdSaleLib makes a check on the token balance, to determine eligibility to withdraw Ether.

https://github.com/Modular-Network/ethereum-libraries/blob/audits/CrowdsaleLib/IICOLib/truffle/contracts/CrowdsaleLib.sol#L204

Problem

I can't see a reason that contract's token balance would need to be checked in order to allow a withdrawal, and I can think of some problem's it might cause.

Document/Add more test cases to TokenLib

Right now there are a good amount of test cases for the Token Library but it could use more test cases for better code coverage.

• Document our current suite of test in order to determine what test cases we have covered

• Use this information to reveal any states that our tests are not covering

• Include tests that use common solidity exploits to ensure our Wallet is resistant to them.

• Expand the tests to include all of these cases and test with testrpc and testnet

Speak with Chris or Josh for help on the WalletLibraries or testing framework. We are happy to help. :)