web3.js/docs/web3-eth-contract.rst

.. _eth-contract:

========
web3.eth.contract
========

The ``web3.eth.contract`` object makes it easy to interact with smart contracts on the ethereum blockchain.
When you create a new contract object you give it the json interface of the respective smart contract
and web3 will auto convert all calls into low level ABI calls over RPC for you.

This allows you to interact with smart contracts as if they were JavaScript objects.


------------------------------------------------------------------------------


new contract
=========

.. index:: JSON interface

.. code-block:: javascript

    new web3.eth.contract(jsonInterface[, address][, options])

Creates a new contract instance with all its methods and events defined in its :ref:`json interface <glossary-json-interface>` object.

----------
Parameters
----------

1. ``Object`` - **jsonInterface**: The json interface for the contract to instantiate
2. ``String`` - **address** (optional): The address of the smart contract to call, can be added later using ``myContract.options.address = '0x1234..'``
3. ``Object`` - **options** (optional): The options of the contract. Some are used as fallbacks for calls and transactions:
    * ``String`` - **from**: The address transactions should be made from.
    * ``String`` - **gasPrice**: The gas price in wei to use for transactions.
    * ``Number`` - **gas**: The maximum gas provided for a transaction (gas limit).
    * ``String`` - **data**: The byte code of the contract. Used when the contract gets :ref:`deployed <contract-deploy>`.

-------
Returns
-------

``Object``: The contract instance with all its methods and events.


-------
Example
-------

.. code-block:: javascript

    var myContract = new web3.eth.contract([...], '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe', {
        from: '0x1234567890123456789012345678901234567891' // default from address
        gasPrice: '20000000000000' // default gas price in wei
    });


------------------------------------------------------------------------------


= Properties =
=========


------------------------------------------------------------------------------

options
=========

.. code-block:: javascript

    myContract.options

The options ``object`` for the contract instance. ``from``, ``gas`` and ``gasPrice`` are used as fallback values when sending transactions.

-------
Properties
-------

``Object`` - options:

- ``String`` - **address**: The address where the contract is deployed. See :ref:`options.address <contract-address>`.
- ``Array`` - **jsonInterface**: The json interface of the contract. See :ref:`options.jsonInterface <contract-json-interface>`.
- ``String`` - **data**: The byte code of the contract. Used when the contract gets :ref:`deployed <contract-deploy>`.
- ``String`` - **from**: The address transactions should be made from.
- ``String`` - **gasPrice**: The gas price in wei to use for transactions.
- ``Number`` - **gas**: The maximum gas provided for a transaction (gas limit).


-------
Example
-------

.. code-block:: javascript

    myContract.options;
    > {
        address: '0x1234567890123456789012345678901234567891',
        jsonInterface: [...],
        from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
        gasPrice: '10000000000000',
        gas: 1000000
    }

    myContract.options.from = '0x1234567890123456789012345678901234567891'; // default from address
    myContract.options.gasPrice = '20000000000000'; // default gas price in wei
    myContract.options.gas = 5000000; // provide as fallback always 5M gas


------------------------------------------------------------------------------

.. _contract-address:

options.address
=========

.. code-block:: javascript

    myContract.options.address

The address used for this contract instance.
All transactions generated by web3.js from this contract will contain this address as the "to".

The address will be stored in lowercase.


-------
Property
-------

``String|null`` - address: The address for this contract, or ``null`` if its not yet set.


-------
Example
-------

.. code-block:: javascript

    myContract.options.address;
    > '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

    // ste a new address
    myContract.options.address = '0x1234FFDD...';


------------------------------------------------------------------------------

.. _contract-json-interface:

options.jsonInterface
=========

.. code-block:: javascript

    myContract.options.jsonInterface

The :ref:`json interface <glossary-json-interface>` object derived from the `ABI <https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI>`_ of this contract.


-------
Property
-------

``Array`` - jsonInterface: The :ref:`json interface <glossary-json-interface>` for this contract. Re-setting this will regenerate the methods and events of the contract instance.


-------
Example
-------

.. code-block:: javascript

    myContract.options.jsonInterface;
    > [{
        "type":"function",
        "name":"foo",
        "inputs": [{"name":"a","type":"uint256"}],
        "outputs": [{"name":"b","type":"address"}]
    },{
        "type":"event",
        "name":"Event"
        "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
    }]

    // set a new interface
    myContract.options.jsonInterface = [...];


------------------------------------------------------------------------------


= Methods =
=========


------------------------------------------------------------------------------


.. _contract-deploy:

.. index:: contract deploy

deploy
=====================

.. code-block:: javascript

    myContract.deploy(options)

Call this function to deploy the contract to the blockchain.
After successfull deployment the ``myContract.options.address`` will be set automatically to the newly deployed contract.

----------
Parameters
----------

1. ``Object`` - **options**: The options used for deployemnt.
    * ``String`` - **data**: The byte code of the contract.
    * ``Array``` - **arguments** (optional): The arguments which get passed to the constructor on deployment.

-------
Returns
-------


``Object``: The transaction object:

- ``Array`` - arguments: The arguments passed to the method before. They can be changed.
- ``Function`` - :ref:`send <contract-send>`: Will deploy the contract.
- ``Function`` - :ref:`estimateGas <contract-estimateGas>`: Will estimate the gas used for deploying.
- ``Function`` - :ref:`encodeABI <contract-encodeABI>`: Encodes the ABI of the deployment, which is contract data + constructor parameters

 For details to the methods see the documentation below.

-------
Example
-------

.. code-block:: javascript

    myContract.deploy({
        data: '0x12345...',
        arguments: [123, 'My String']
    })
    .send({
        from: '0x1234567890123456789012345678901234567891',
        gas: 1500000,
        gasPrice: '30000000000000'
    }, function(error, transactionHash){ ... })
    .on('error', function(error){ ... })
    .on('transactionHash', function(transactionHash){ ... })
    .on('receipt', function(receipt){
        // same as when the promise gets resolved, see below
    })
    .on('confirmation', function(confirmationNumber, receipt){ ... })
    .then(function(receipt){
        console.log(myContract.options.address) // gives the new contract address
    });


    // When the data is already set as an option to the contract itself
    myContract.options.data = '0x12345...';

    myContract.deploy({
        arguments: [123, 'My String']
    })
    .send({
        from: '0x1234567890123456789012345678901234567891',
        gas: 1500000,
        gasPrice: '30000000000000'
    })
    .then(function(receipt){
        console.log(myContract.options.address) // gives the new contract address
    });


    // Simply encoding
    myContract.deploy({
        data: '0x12345...',
        arguments: [123, 'My String']
    })
    .encodeABI();
    > '0x12345...0000012345678765432'


    // Gas estimation
    myContract.deploy({
        data: '0x12345...',
        arguments: [123, 'My String']
    })
    .estimateGas(function(err, gas){
        console.log(gas);
    });

------------------------------------------------------------------------------


methods
=====================

.. code-block:: javascript

    myContract.methods.myMethod([param1[, param2[, ...]]])

Creates a transaction object for that method, which then can be :ref:`called <contract-call>`, :ref:`send <contract-send>`, :ref:`estimated  <contract-estimateGas>`or :ref:`ABI encoded <contract-encodeABI>`.

The methods of this smart contract are available through:

- The name: ``myContract.methods.myMethod(123)``
- The name with parameters: ``myContract.methods['myMethod(uint256)'](123)``
- The signature: ``myContract.methods['0x58cf5f10'](123)``

This allows calling functions with same name but different parameters from the JavaScript contract object.

----------
Parameters
----------

Parameters of any method depend on the smart contracts methods, defined in the :ref:`JSON interface <glossary-json-interface>`.

-------
Returns
-------

``Object``: The transaction object:

- ``Array`` - arguments: The arguments passed to the method before. They can be changed.
- ``Function`` - :ref:`call <contract-call>`: Will call the "constant" method and execute its smart contract method in the EVM without sending a transaction (Can't alter the smart contract state).
- ``Function`` - :ref:`send <contract-send>`: Will send a transaction to the smart contract and execute its method (Can alter the smart contract state).
- ``Function`` - :ref:`estimateGas <contract-estimateGas>`: Will estimate the gas used when the method would be executed on chain.
- ``Function`` - :ref:`encodeABI <contract-encodeABI>`: Encodes the ABI for this method. This can be send using a transaction, call the method or passing into another smart contracts method as argument.

 For details to the methods see the documentation below.

-------
Example
-------

.. code-block:: javascript

    // calling a method

    myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, result){
        ...
    });

    // or sending and using a promise
    myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .then(function(receipt){
        ...
    });

    // or sending and using the events

    myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .on('transactionHash', function(hash){
        ...
    })
    .on('receipt', function(receipt){
        ...
    })
    .on('confirmation', function(confirmationNumber, receipt){ ... })
    .on('error', console.error);


------------------------------------------------------------------------------


.. _contract-call:

methods.myMethod.call
=====================

.. code-block:: javascript

    myContract.methods.myMethod([param1[, param2[, ...]]]).call(options[, callback])

Will call a "constant" method and execute its smart contract method in the EVM without sending any transaction. Note calling can not alter the smart contract state.

----------
Parameters
----------

1. ``Object`` - **options** (optional): The options used for calling.
    * ``String`` - **from** (optional): The address the call "transaction" should be made from.
    * ``String`` - **gasPrice** (optional): The gas price in wei to use for this call "transaction".
    * ``Number`` - **gas** (optional): The maximum gas provided for this call "transaction" (gas limit).
2. ``Function`` - **callback** (optional): This callback will be fired with the result of the smart contract method execution as the second argument, or with an error object as the first argument.

-------
Returns
-------

``Promise`` returns ``Mixed``: The return value(s) of the smart contract method.

// TODO add specific examples, once the decoder is extended

-------
Example
-------

.. code-block:: javascript

    // using the callback
    myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, result){
        ...
    });

    // using the promise
    myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .then(function(result){
        ...
    });


------------------------------------------------------------------------------


.. _contract-send:

methods.myMethod.send
=====================

.. code-block:: javascript

    myContract.methods.myMethod([param1[, param2[, ...]]]).send(options[, callback])

Will send a transaction to the smart contract and execute its method. Note this can alter the smart contract state.

----------
Parameters
----------

1. ``Object`` - **options**: The options used for sending.
    * ``String`` - **from**: The address the transaction should be send from.
    * ``String`` - **gasPrice** (optional): The gas price in wei to use for this transaction.
    * ``Number`` - **gas** (optional): The maximum gas provided for this transaction (gas limit).
2. ``Function`` - **callback** (optional): This callback will be fired first with the "transactionHash", or with an error object as the first argument.

-------
Returns
-------

``PromiEvent``:  A promise combined event emitter. Will be resolved when the transaction *receipt* is available. Additionally the following events are available:

- ``"transactionHash"`` returns ``String``: is fired right after the transaction is send and a transaction hash is available.
- ``"receipt"`` returns ``Object``: is fired when the transaction receipt is available.
- ``"confirmation"`` returns ``Number``, ``Object``: is fired for every confirmation up to the 12th confirmation. Receives the confirmation number as the first and the receipt as the second argument. Fired from confirmation 0 on, which is the block where its minded.
- ``"error"`` returns ``Error``: is fired if an error occurs during deployment.


-------
Example
-------

.. code-block:: javascript

    // using the callback
    myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, hash){
        ...
    });

    // using the promise
    myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .then(function(receipt){
        ...
    });


    // using the event emitter
    myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .on('transactionHash', function(hash){
        ...
    })
    .on('receipt', function(receipt){
        ...
    })
    .on('confirmation', function(confirmationNumber, receipt){ ... })
    .on('error', console.error);


------------------------------------------------------------------------------


.. _contract-estimateGas:

methods.myMethod.estimateGas
=====================

.. code-block:: javascript

    myContract.methods.myMethod([param1[, param2[, ...]]]).estimateGas(options[, callback])

Will call estimate the gas a method execution will take when executed in the EVM without.
The estimation can differ from the actual gas used when later sending a transaction, as the state of the smart contract can be different at that time.

----------
Parameters
----------

1. ``Object`` - **options** (optional): The options used for calling.
    * ``String`` - **from** (optional): The address the call "transaction" should be made from.
    * ``Number`` - **gas** (optional): The maximum gas provided for this call "transaction" (gas limit). Setting a specific value helps to detect out of gas errors. If all gas is used it will return the same number.
2. ``Function`` - **callback** (optional): This callback will be fired with the result of the gas estimation as the second argument, or with an error object as the first argument.

-------
Returns
-------

``Promise`` returns ``Number``: The gas amount estimated.

-------
Example
-------

.. code-block:: javascript

    // using the callback
    myContract.methods.myMethod(123).estimateGas({gas: 5000000}, function(error, gasAmount){
        if(gasAmount == 5000000)
            console.log('Method ran out of gas');
    });

    // using the promise
    myContract.methods.myMethod(123).estimateGas({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
    .then(function(gasAmount){
        ...
    });


------------------------------------------------------------------------------


.. _contract-encodeABI:

methods.myMethod.encodeABI
=====================

.. code-block:: javascript

    myContract.methods.myMethod([param1[, param2[, ...]]]).encodeABI()

Encodes the ABI for this method. This can be used to send a transaction, call a method or pass it into another smart contracts method as argument.


----------
Parameters
----------

none

-------
Returns
-------

``String``: The encoded ABI byte code to send via a transaction or call.

-------
Example
-------

.. code-block:: javascript

    myContract.methods.myMethod(123).encodeABI();
    > '0x58cf5f1000000000000000000000000000000000000000000000000000000000000007B'


------------------------------------------------------------------------------


= Events =
=========


------------------------------------------------------------------------------


getPastEvents
=====================

.. code-block:: javascript

    myContract.getPastEvents(event[, options][, callback])

Gets past events for this contract.

----------
Parameters
----------

1. ``String`` - **event**: The name of the event in the contract, or ``"allEvents"`` to get all events.
2. ``Object`` - **options** (optional): The options used for deployment.
    * ``Object`` - **filter** (optional): Let you filter events by indexed parameters, e.g. ``{filter: {myNumber: [12,13]}}`` means all events where "myNumber" is 12 or 13.
    * ``Number`` - **fromBlock** (optional): The block number from which to get events on.
    * ``Number`` - **toBlock** (optional): The block number until events to get (Defaults to ``"latest"``).
    * ``Array`` - **topics** (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature (topic[0]) will not be set automatically.
3. ``Function`` - **callback** (optional): This callback will be fired with an array of event logs as the second argument, or an error as the first argument.


.. _contract-getPastEvents-return:

-------
Returns
-------

``Promise`` returns ``Array``: An array with the past event ``Objects``, matching the given event name and filter.

The structure of the returned event ``Object`` in the ``Arrray`` looks as follows:

- ``Object`` - **returnValues**: The return values coming from the event, e.g. ``{myVar: 1, myVar2: '0x234...'}``.
- ``String`` - **event**: The event name.
- ``Number`` - **logIndex**: Integer of the event index position in the block.
- ``Number`` - **transactionIndex**: Integer of the transaction's index position, the event was created in.
- ``String`` 32 Bytes - **transactionHash**: Hash of the transaction this event was created in.
- ``String`` 32 Bytes - **blockHash**: Hash of the block where this event was created in. ``null`` when its still pending.
- ``Number`` - **blockNumber**: The block number where this log was created in. ``null`` when still pending.
- ``String`` - **address**: from which this event originated from.

-------
Example
-------

.. code-block:: javascript

    myContract.getPastEvents('MyEvent', {
        filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
        fromBlock: 0,
        toBlock: 'latest'
    }, function(error, events){ console.log(events); })
    .then(function(events){
        console.log(events) // same results as the optional callback above
    });

    > [{
        returnValues: {
            myIndexedParam: 20,
            myOtherIndexedParam: '0x123456789...',
            myNonIndexParam: 'My String'
        },
        event: 'MyEvent',
        logIndex: 0,
        transactionIndex: 0,
        transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
        blockNumber: 1234,
        address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
    },{
        ...
    }]


------------------------------------------------------------------------------


once
=====================

.. code-block:: javascript

    myContract.once(event[, options], callback)

Subscribes to an event, and unsubscribes immediately after the first event or error. Will fire only for one event.

----------
Parameters
----------

1. ``String`` - **event**: The name of the event in the contract, or ``"allEvents"`` to get all events.
2. ``Object`` - **options** (optional): The options used for deployment.
    * ``Object`` - **filter** (optional): Let you filter events by indexed parameters, e.g. ``{filter: {myNumber: [12,13]}}`` means all events where "myNumber" is 12 or 13.
    * ``Array`` - **topics** (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature (topic[0]) will not be set automatically.
3. ``Function`` - **callback**: This callback will be fired for the first event as the second argument, or an error as the first argument.

-------
Returns
-------

``undefined``

-------
Example
-------

.. code-block:: javascript

    myContract.once('MyEvent', {
        filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
        fromBlock: 0
    }, function(error, event){ console.log(event); });

    // event output example
    > {
        returnValues: {
            myIndexedParam: 20,
            myOtherIndexedParam: '0x123456789...',
            myNonIndexParam: 'My String'
        },
        event: 'MyEvent',
        logIndex: 0,
        transactionIndex: 0,
        transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
        blockNumber: 1234,
        address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
    }


------------------------------------------------------------------------------

.. _contract-events:

events
=====================

.. code-block:: javascript

    myContract.events.MyEvent([options][, callback])

Subscribe to a event

----------
Parameters
----------

1. ``Object`` - **options** (optional): The options used for deployment.
    * ``Object`` - **filter** (optional): Let you filter events by indexed parameters, e.g. ``{filter: {myNumber: [12,13]}}`` means all events where "myNumber" is 12 or 13.
    * ``Number`` - **fromBlock** (optional): The block number from which to get events on.
    * ``Array`` - **topics** (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature (topic[0]) will not be set automatically.
2. ``Function`` - **callback** (optional): This callback will be fired for each event as the second argument, or an error as the first argument.

-------
Returns
-------

``EventEmitter``: The event emitter has the following events:

- ``"data"`` returns ``Object``: Fires on each incoming event with the event object as argument.
- ``"changed"`` returns ``Object``: Fires on each event which was removed from the blockchain. The event will have the additional property ``"removed: true"``.
- ``"error"`` returns ``Object``: Fires when an error in the subscription occours.

For the structure of a returned event ``Object`` see :ref:`getPastEvents return values <contract-getPastEvents-return>`.

-------
Example
-------

.. code-block:: javascript

    myContract.events.MyEvent({
        filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
        fromBlock: 0
    }, function(error, event){ console.log(event); })
    .on('data', function(event){
        console.log(event); // same results as the optional callback above
    })
    .on('changed', function(event){
        // remove event from local database
    })
    .on('error', console.error);

    // event output example
    > {
        returnValues: {
            myIndexedParam: 20,
            myOtherIndexedParam: '0x123456789...',
            myNonIndexParam: 'My String'
        },
        event: 'MyEvent',
        logIndex: 0,
        transactionIndex: 0,
        transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
        blockNumber: 1234,
        address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
    }


------------------------------------------------------------------------------

events.allEvents
=====================

.. code-block:: javascript

    myContract.events.allEvents([options][, callback])

Same as :ref:`events <contract-events>` but receives all events from this smart contract.
Optionally the filter property can filter those events.