❤
npm
Sign UpSign In

ethereum-libraries-token

1.3.4 • Public • Published

TokenLib

Build Status Discord

A library provided by Modular to abstract token creation. This library was inspired by Aragon's blog post on library usage .

Library Address

Main Ethereum Network: 0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a
Rinkeby Test Network: 0xd8688508661deaf4fb69bde3e100e89ee1b02056

License and Warranty

Be advised that while we strive to provide professional grade, tested code we cannot guarantee its fitness for your application. This is released under The MIT License (MIT) and as such we will not be held liable for lost funds, etc. Please use your best judgment and note the following:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Installation and Usage

How to install

npm install ethereum-libraries-token

How to link

Amend the deployment .js file in your truffle migrations/ directory as follows:

var BasicMathLib = artifacts.require("ethereum-libraries-basic-math/contracts/BasicMathLib.sol");
var TokenLib = artifacts.require("./TokenLib.sol");
var OtherLibs = artifacts.require("./OtherLibs.sol");
var YourStandardTokenContract = artifacts.require("./YourStandardTokenContract.sol");
...
 
//Input your parameters
var name = //"Your Token Name";
var symbol = //"YTS";
var decimals = //18;
var initialSupply = //10;
module.exports = function(deployer) {
  deployer.deploy(BasicMathLib,{overwrite: false});
  deployer.link(BasicMathLib, TokenLib);
  deployer.deploy(TokenLib, {overwrite: false});
  deployer.link(TokenLib, YourStandardTokenContract);
  deployer.deploy(YourStandardTokenContract, name, symbol, decimals, initialSupply);
};

Note: If you have not created a second deployment .js file in the migrations/ directory, this needs to be done first. You cannot use the 1_initial_migration.js file for your migrations.

Note: The .link() function should be called before you .deploy(YourStandardTokenContract). Also, be sure to include the {overwrite: false} when writing the deployer i.e. .deploy(TokenLib, {overwrite: false}). This prevents deploying the library onto the main network or Rinkeby test network at your cost and uses the library already on the blockchain. The function should still be called however because it allows you to use it in your development environment. See below

Testing

Test: npm run test

Test Coverage: Solidity coverage is not currently emitting events properly for Solidity v0.4.21

solc Installation

version 0.4.21

For direction and instructions on how the Solidity command line compiler works see the documentation.

With standard JSON input

The Standard JSON Input provides an easy interface to include libraries. Include the following as part of your JSON input file:

{
  "language": "Solidity",
  "sources":
  {
    "YourContract.sol": {
      ...
      ...
    },
    "BasicMathLib.sol": {
      "content": "[Contents of BasicMathLib.sol]"
    },
    "TokenLib.sol": {
      "content": "[Contents of TokenLib.sol]"
    }
  },
  "settings":
  {
    ...
    "libraries": {
      "TokenLib.sol": {
        "BasicMathLib" : "0xD08660d7298CDc78169D6f8C99C3141a9D59A3d3"
      },
      "YourTokenContract.sol": {
        "TokenLib": "0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a"
      }
    }
  }
}

Note: The library name should match the name used in your contract.

solc without standard JSON input

When creating unlinked binary, the compiler currently leaves special substrings in the compiled bytecode in the form of 'LibraryName____' which leaves a 20 byte space for the library's address. In order to include the deployed library in your bytecode add the following flag to your command:

--libraries "TokenLib:0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a"

Additionally, if you have multiple libraries, you can create a file with one library string per line and include this library as follows:

"TokenLib:0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a"

then add the following flag to your command:

--libraries filename

Finally, if you have an unlinked binary already stored with the 'LibraryName____' placeholder, you can run the compiler with the --link flag and also include the following flag:

--libraries "TokenLib:0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a"

solc documentation

See the solc documentation for further information.

solc-js Installation

version 0.4.21

Solc-js provides javascript bindings for the Solidity compiler and can be found here. Please refer to their documentation for detailed use.

This version of Solc-js also uses the standard JSON input to compile a contract. The entry function is compileStandardWrapper() and you can create a standard JSON object explained under the solc section and incorporate it as follows:

var solc = require('solc');
var fs = require('fs');
 
var file = fs.readFileSync('/path/to/YourTokenContract.sol','utf8');
var basicMath = fs.readFileSync('./path/to/BasicMathLib.sol','utf8');
var lib = fs.readFileSync('./path/to/TokenLib.sol','utf8');
 
var input = {
  "language": "Solidity",
  "sources":
  {
    "YourTokenContract.sol": {
      "content": file
    },
    "BasicMathLib": {
      "content": basicMath
    },
    "TokenLib.sol": {
      "content": lib
    }
  },
  "settings":
  {
    ...
    "libraries": {
      "TokenLib": {
        "BasicMathLib": "0xD08660d7298CDc78169D6f8C99C3141a9D59A3d3"
      },
      "YourContract.sol": {
        "TokenLib": "0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a"
      }
    }
    ...
  }
}
 
var output = JSON.parse(solc.compileStandardWrapper(JSON.stringify(input)));
 
//Where the output variable is a standard JSON output object.

Solc-js Installation via Linking

Solc-js also provides a linking method if you have compiled binary code already with the placeholder. To link this library the call would be:

bytecode = solc.linkBytecode(bytecode, { 'TokenLib': '0xA699Dd7D57917a57FA9d0E323Ab4b542a0Ff873a' });

Solc-js documentation

See the Solc-js documentation for further information.

Basic Usage

Disclaimer: While we make every effort to produce professional grade code we can not guarantee the security and performance of these libraries in your smart contracts. Please use good judgement and security practices while developing, we do not take responsibility for any issues you, your customers, or your applications encounter when using these open source resources.

For a detailed explanation on how libraries are used please read the following from the Solidity documentation:

The TokenLib abstracts away all of the functions required for several token variations. Users will include this library in their token contract and use it to make state changes.

In order to use the TokenLib, import it into your token contract and then bind it as follows:

Usage Example

pragma solidity ^0.4.21;

import "ethereum-libraries-token/contracts/TokenLib.sol";

contract TokenContract {
  using TokenLib for TokenLib.TokenStorage;

  TokenLib.TokenStorage token;

  function TokenContract(address owner,
                                string name,
                                string symbol,
                                uint8 decimals,
                                uint256 initialSupply,
                                bool allowMinting) {
    token.init(name, symbol, decimals, initialSupply, allowMinting);
  }

  function owner() constant returns (string) {
    return token.owner;
  }

  function name() constant returns (string) {
    return token.name;
  }

  ...
}

Binding the library allows you to call the function in the format [firstParameter].function(secondParameter) . For a complete ERC20 standard token example, please visit our Ethereum Contracts repository.

Change Log

v1.3.0

  • Upgraded to compiler v0.4.21

  • Moved into its own node package

v1.2.0

  • Changed INITIAL_SUPPLY to initialSupply since it is not a defined constant at runtime.

  • Changed the initialization check to an initialization flag as suggested by Noel Maersk.

  • Changed approve function to check for current approval to be 0 before changing to be more inline with the current spec.

v1.1.0

  • Changed the init() function to set the balance of the _owner as the initial supply. It was previously the msg.sender.

Functions

The following is the list of functions available to use in your token contract.

Standard Token Functions

init(TokenLib.TokenStorage storage, address, string, string, uint8, uint256, bool) public

(TokenLib.sol, line 64)

Initialize token with owner address, token name, symbol, decimals, supply, and minting status. Standard decimals is 18, the decimals used for Ether. If no additional tokens will be minted _allowMinting should be false.

Arguments

TokenLib.TokenStorage storage self The storage token in the calling contract.
address _owner Owning address of token contract. string _name Name of the token.
string _symbol Symbol of the token.
uint8 _decimals Decimal places for token represented.
uint256 _initial_supply Initial supply for the token.
bool _allowMinting True if more tokens will be created, false otherwise.

Returns

Nada

transfer(TokenLib.TokenStorage storage, address, uint256) public returns (bool)

(TokenLib.sol, line 90)

Transfer tokens from msg.sender to another account.

Arguments

TokenLib.TokenStorage storage variable self
address _to
uint256 _value

Returns

bool Returns true after successful transfer.

transferFrom(TokenLib.TokenStorage storage, address, address, uint256) public returns (bool)

(TokenLib.sol, line 110)

Authorized spender, msg.sender, transfers tokens from one account to another.

Arguments

TokenLib.TokenStorage storage self
address _from
address _to
uint256 _value

Returns

bool

balanceOf(TokenLib.TokenStorage storage, address) public vew returns (uint256)

(TokenLib.sol, line 140)

Retrieve the token balance of the given account.

Arguments

TokenLib.TokenStorage storage self
address _owner

Returns

uint256 balance

approve(TokenLib.TokenStorage storage, address, uint256) public returns (bool)

(TokenLib.sol, line 149)

msg.sender approves a third party to spend up to _value in tokens.

Arguments

TokenLib.TokenStorage storage self
address _spender
uint256 _value

Returns

bool

allowance(TokenLib.TokenStorage storage, address, address) public view returns (uint256)

(TokenLib.sol, line 163)

Check the remaining allowance spender has from owner.

Arguments

TokenStorage storage self
address _owner
address _spender

Returns

uint256 remaining

Enhanced Token Functions

These are additional functions beyond the standard that can enhance token functionality.

approveChange(TokenLib.TokenStorage storage, address, uint256, bool) public returns (bool)

(TokenLib.sol, line 177)

msg.sender approves a third party to spend tokens by increasing or decreasing the allowance by an amount equal to _valueChange. _increase should be true if increasing the approval amount and false if decreasing the approval amount. This is an enhancement to the approve function which subverts the attack vector described here by acting on the allowance delta rather than the amount explicitly.

Arguments

TokenLib.TokenStorage storage self
address _spender
uint256 _valueChange The amount to change approval by.
bool _increase True if increasing approval, false if decreasing.

Returns

bool

changeOwner(TokenLib.TokenStorage storage, address) public returns (bool)

(TokenLib.sol, line 204)

Changes the owning address of the token contract.

Arguments

TokenLib.TokenStorage storage self
address _newOwner

Returns

bool

mintToken(TokenLib.TokenStorage storage, uint256) public returns (bool)

(TokenLib.sol, line 216)

Mints new tokens if allowed, increases totalSupply. New tokens go to the token contract owner address.

Arguments

TokenLib.TokenStorage storage self
uint256 _value Amount of tokens to mint.

Returns

bool

closeMint(TokenLib.TokenStorage storage) public returns (bool)

(TokenLib.sol, line 233)

Permanently closes minting capability.

Arguments

TokenLib.TokenStorage storage self

Returns

bool

burnToken(TokenLib.TokenStorage storage, uint256) public returns (bool)

(TokenLib.sol, line 245)

Allows to permanently burn tokens, reduces totalSupply.

Arguments

TokenLib.TokenStorage storage self
uint256 _value Amount of tokens to burn.

Returns

bool

Readme

Keywords

Package Sidebar

Install

npm i ethereum-libraries-token

Repository

github.com/Modular-Network/ethereum-libraries

Homepage

github.com/Modular-Network/ethereum-libraries

Weekly Downloads

1

Version

1.3.4

License

MIT

Unpacked Size

1.14 MB

Total Files

17

Last publish

Collaborators

  • hackdom
Try on RunKit
Report malware