Nodeschool Public Materials

    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

    Install

    npm i ethereum-libraries-token

    DownloadsWeekly Downloads

    2

    Version

    1.3.4

    License

    MIT

    Unpacked Size

    1.14 MB

    Total Files

    17

    Last publish

    Collaborators

    • hackdom