.. _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 <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.address = '0x1234..'``
3. ``Object`` - **options** (optional): The fallback options used for calls and transactions made to this contract:
    * ``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).

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

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


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

.. code-block:: javascript

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


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


Contract Properties
=========


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

options
=========

.. code-block:: javascript

    myContract.options

The options ``object`` for the contract instance. Contains mostly values which will be used as fallback values for sending transactions.

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

``Object`` - options:

- ``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;
    > {
        from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
        gasPrice: '10000000000000'
    }

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


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


address
=========

.. code-block:: javascript

    myContract.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.address;
    > '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

    myContract.address = '0x1234FFDD...';


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


jsonInterface
=========

.. code-block:: javascript

    myContract.jsonInterface

The :ref:`json interface <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 <json-interface>` for this contract. Re-setting this will regenerate the methods and events of the contract instance.


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

.. code-block:: javascript

    myContract.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.jsonInterface = [...];


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


Contract Methods
=========