Getting Started

React

Reference

Contract Abstractions

Truffle provides contract abstractions for interacting with your contracts. Skip ahead to the api section for a list of contract methods.

Usage

To obtain a contract abstraction you can require it with the contract name from the artifacts object. Outside of the console this is an object available in migration files, tests, and exec scripts.
You would require your contract as follows:

const MyContract = artifacts.require("MyContract");

You can also obtain one in the developer console. Your contract types are available here and all you need to do is use the at, deployed, or new method.

truffle(development)> const myContract = await MyContract.deployed();

You now have access to the following functions on MyContract, as well as many others:

at(): Create an instance of MyContract that represents your contract at a specific address.

deployed(): Create an instance of MyContract that represents the default address managed by MyContract.

new(): Deploy a new version of this contract to the network, getting an instance of MyContract that represents the newly deployed instance.

Each instance is tied to a specific address on the Ethereum network, and each instance has a 1-to-1 mapping from Javascript functions to contract functions. For instance, if your Solidity contract had a function defined someFunction(uint value) {} (solidity), then you could execute that function on the network like so:

You can also use async/await syntax which is often much less verbose.
We will use async/await for the rest of this document but you may also use a promises for interfacing with contract methods as well.

const deployed = await MyContract.deployed();
const result = await deployed.someFunction(5);
// Do something with the result or continue with more transactions.

API

There are two API's you'll need to be aware of. One is the static Contract Abstraction API and the other is the Contract Instance API. The Abstraction API is a set of functions that exist for all contract abstractions, and those function exist on the abstraction itself (i.e., MyContract.at()). In contrast, the Instance API is the API available to contract instances -- i.e., abstractions that represent a specific contract on the network -- and that API is created dynamically based on functions available in your Solidity source file.

Contract Abstraction API

Each contract abstraction -- MyContract in the examples above -- have the following useful functions:

MyContract.new([arg1, arg2, ...], [tx params])

This function take whatever contructor parameters your contract requires and deploys a new instance of the contract to the network. There's an optional last argument which you can use to pass transaction parameters including the transaction from address, gas limit and gas price. This function returns a Promise that resolves into a new instance of the contract abstraction at the newly deployed address.

MyContract.at(address)

This function creates a new instance of the contract abstraction representing the contract at the passed in address. Returns a "thenable" object (not yet an actual Promise for backward compatibility). Resolves to a contract abstraction instance after ensuring code exists at the specified address.

MyContract.deployed()

Creates an instance of the contract abstraction representing the contract at its deployed address. The deployed address is a special value given to truffle-contract that, when set, saves the address internally so that the deployed address can be inferred from the given Ethereum network being used. This allows you to write code referring to a specific deployed contract without having to manage those addresses yourself. Like at(), deployed() is thenable, and will resolve to a contract abstraction instance representing the deployed contract after ensuring that code exists at that location and that that address exists on the network being used.

MyContract.link(instance)

Link a library represented by a contract abstraction instance to MyContract. The library must first be deployed and have its deployed address set. The name and deployed address will be inferred from the contract abstraction instance. When this form of MyContract.link() is used, MyContract will consume all of the linked library's events and will be able to report that those events occurred during the result of a transaction.

Libraries can be linked multiple times and will overwrite their previous linkage.

Note: This method has two other forms, but this form is recommended.

MyContract.link(name, address)

Link a library with a specific name and address to MyContract. The library's events will not be consumed using this form.

MyContract.link(object)

Link multiple libraries denoted by an Object to MyContract. The keys must be strings representing the library names and the values must be strings representing the addresses. Like above, libraries' events will not be consumed using this form.

MyContract.networks()

View a list of network ids this contract abstraction has been set up to represent.

MyContract.setProvider(provider)

Sets the web3 provider this contract abstraction will use to make transactions.

MyContract.setNetwork(network_id)

Sets the network that MyContract is currently representing.

MyContract.hasNetwork(network_id)

Returns a boolean denoting whether or not this contract abstraction is set up to represent a specific network.

MyContract.defaults([new_defaults])

Get's and optionally sets transaction defaults for all instances created from this abstraction. If called without any parameters it will simply return an Object representing current defaults. If an Object is passed, this will set new defaults. Example default transaction values that can be set are:

Setting a default from address, for instance, is useful when you have a contract abstraction you intend to represent one user (i.e., one address).

MyContract.clone(network_id)

Clone a contract abstraction to get another object that manages the same contract artifacts, but using a different network_id. This is useful if you'd like to manage the same contract but on a different network. When using this function, don't forget to set the correct provider afterward.

const MyOtherContract = MyContract.clone(1337);

MyContract.numberFormat = number_type

You can set this property to choose the number format that abstraction methods return. The default behavior is to return BN.

MyContract.timeout(block_timeout)

This method allows you to set the block timeout for transactions. Contract instances created from this abstraction will have the specified transaction block timeout. This means that if a transaction does not immediately get mined, it will retry for the specified number of blocks.

MyContract.autoGas = <boolean>

If this is set to true, instances created from this abstraction will use web3.eth.estimateGas and then apply a gas multiplier to determine the amount of gas to include with the transaction. The default value for this is true. See gasMultiplier.

MyContract.gasMultiplier(gas_multiplier)

This is the value used when autoGas is enabled to determine the amount of gas to include with transactions. The gas is computed by using web3.eth.estimateGas and multiplying it by the gas multiplier. The default value is 1.25.

Contract Instance API

Each contract instance is different based on the source Solidity contract, and the API is created dynamically. For the purposes of this documentation, let's use the following Solidity source code below:

Note that if the function being executed in the transaction has a return value, you will not get that
return value inside this result. You must instead use an event (like ValueSet) and look up the result
in the logs array.

Explicitly making a call instead of a transaction

We can call setValue() without creating a transaction by explicitly using .call:

const value = await instance.setValue.call(5);

This isn't very useful in this case, since setValue() sets things, and the value we pass won't be saved since we're not creating a transaction.

Calling getters

However, we can get the value using getValue(), using .call(). Calls are always free and don't cost any Ether, so they're good for calling functions that read data off the blockchain:

Even more helpful, however is we don't even need to use .call when a function is marked as constant, because truffle-contract will automatically know that that function can only be interacted with via a call:

Processing transaction results

When you make a transaction, you're given a result object that gives you a wealth of information about the transaction. You're given the transaction has (result.tx), the decoded events (also known as logs; result.logs), and a transaction receipt (result.receipt). In the below example, you'll recieve the ValueSet() event because you triggered the event using the setValue() function: