Pre-release: v4.0.0 (beta)

Hi all. 👋

We've got a whirlwind release for you packed with tons of tasty goodness. This is a BETA release. And it's a BIG release -- we'll want your feedback. To get it, see below. And make sure to checkout the upgrade section before installing the new version.

This release is so hot 🔥, packed with so much 💪, that we needed to take a new approach to our release notes. So sit back, grab a 🍹, and check out everything we have in store.

Introducing the Integrated Solidity Debugger

That's right folks. You read that correctly. With Truffle 4.0, you can now debug your Ethereum transactions with full Solidity source code mapping. Debug any transaction. On any chain.*

Debugging an Ethereum transaction is different than debugging a traditional application. On Ethereum, all application state is saved on a world computer and can be introspected at any time. By debugging a transaction, you're really stepping through history rather than executing code in real time.

This gives you a lot of power. Here's a list of everything you can do with the debugger:

• Debug past transactions like you'd debug a normal application. Step over, step into, step next, it's all there.
• Debug transactions without code. That's right, you can even inspect transactions that you don't have the code for. You won't see any mapping to Solidity source code, since it's not there, but the debugger will provide you important stack and instruction information to understand what's happening within that transaction.
• Figure out exactly where your transaction errored (think, throw, revert(), assert(), etc.)
• Figure out the exact point in which your transaction ran out of gas.
• Inspect individual instructions and their related stack information.
• See the address associated with each line of code.

This is a big step for Solidity development. And it's all here, included in Truffle.

* Note: Your Ethereum client must support eth_debugTraceTransaction. The latest TestRPC does, as does go-ethereum.

Using the debugger

Since debugging on Ethereum is different, this means you can only debug past transactions. So to use the debugger, first find the hash of the transaction you want to debug, and then run the following command, replacing your transaction hash with the one shown below:

$ truffle debug 0x9b595a1760b0b7791a9ae56ba6dd28060522250e94e16591a880e4279904a187

As the debugger initializes, you'll see that it analyzes the transaction to find all contracts that it interacts with over the course of its execution. This includes currently existing contracts, and contracts created as a result of the transaction. Then, it'll look at your Truffle project to see if it can match those contracts up to code. If so, you'll see your Solidity code as you step through every part of your contract's execution. Sweet, isn't it?

Note that Truffle is looking for exact matches of binaries when matching up your contract's code to what's on chain. If you change your compiler version, for instance, by upgrading to a new version of Truffle which has a later Solidity compiler, this may present a problem when debugging previously deployed transactions. Though we don't have a solution for this yet, we hope to build one in the near future. Stay tuned!

Truffle Develop: Zero-to-Code in 1 second

Most users' first action after installing Truffle is to install the TestRPC. Now, there's no need: An integrated development blockchain powered by ganache-core comes standard. And you can get to it with a single command:

$ truffle develop

After firing up truffle develop, not only do you get a development blockchain that comes with zero installation, but you also get a direct line into that blockchain via the console. Type commands like compile and migrate as you would if you were using the console on its own. You can also access your contract abstractions as well, as they're automatically reloaded for you after every command. See our console documentation for more information.

Using truffle develop has some other benefits over running the TestRPC directly:

• It has a consistent host and port that doesn't conflict with the popular port. It always runs on http://localhost:9545
• It always has the same network id (4447) so you'll know that's the dev environment when you see that id in your artifacts.
• It's deterministic, using the same seed every time. For power users, the seed is yum chocolate. 🍫
• And it requires no extra installation.

So be stoked. That's one small step for Truffle, and one giant leap for your development process. 🚀

Testing Made Simpler

With truffle develop, you can get a development environment in a pinch. Now the same is true for testing: In this new release, truffle test will fire up a default test environment to run in. Simply type truffle test and away it goes! No need to set up a TestRPC. No need to futz with your environment.

For all you Truffle veterans though, there's a catch: You need to remove your development network from your truffle.js config file if you'd like to use this feature. We did this so upgrading to Truffle 4.0 doesn't completely blow away your testing process. You're welcome. 😃

That said, get this: the test command works great in truffle develop, so you can get the same behavior if you make truffle develop your environment of choice. It's up to you!

Dry Run: Take the Guesswork Out of Migrations

Ever tried to deploy your contracts against the live chain (using real 💲!) and wondered, "Is this gonna work?". Well fret no more. We've integrated the power of ganache-core directly into Truffle. You can now test your migrations on your chain of choice before actually deploying them, using the now-included --dry-run feature:

$ truffle migrate --dry-run

Under the hood, this feature will fork from your chain of choice and create a new sandbox to run your migrations. This sandbox has access to all the code, addresses, accounts and balances on the old chain, but all new transactions occur within the sandbox. This means you can test upgrading those complex upgradable contracts before actually upgrading them. Aces. 🎯

Note: In order for this feature to work, your main Ethereum client must be running and accessible during the --dry-run process.

---

Updating to Truffle 4.0 from 3.x

For most users, updating to Truffle 4.0 from 3.x is seamless: You simply need to install the new version. However, there's one gotcha that might affect some users. Before we get to that, your TL;DR:

1. Install the new version of Truffle
2. Upgrade truffle-contract to v3.0.0 for any project that uses it (like frontends)
3. Run truffle compile --all to auto-upgrade contract artifacts and unlock debugging features.

Now for the nitty gritty...

In order to support debugging, the artifact format for Truffle contracts has changed (these are all the files that live in ./build/contracts). The new format provides all the information needed to easily debug your contracts. There's one catch: You may have to do some upgrading. The good news is most of the upgrade is done automatically.

(Aside! We formalized and standardized our contract schema so you can write programs that interact with that format, too. Check it out! 🎉)

Let's dive in.

Install the new version of Truffle

First you need to install the new version of Truffle. Remember that this is the beta release, so the process will be slightly different from before.

We'll start by uninstalling the old version of Truffle, if present:

$ npm uninstall -g truffle

Next, install the new version using the beta flag:

$ npm install -g truffle@beta

If you're on Ubuntu or OS X, you may need to use sudo in the above commands.

Update truffle-contract to v3.0.0

Projects that interact with Truffle-created contracts, like frontends, usually do so by interfacing through the truffle-contract library. If you have a project that uses truffle-contract, you'll need to update that project's package.json to include truffle-contract v3.0.0 instead of the older version.

This upgrade should be seamless for most users, and you shouldn't have to update your project's code unless you use a contract's .toJSON() function. Since the internal JSON representation has changed, the output that function returns will be different.

If you do not use .toJSON() and you notice the upgrade doesn't go seamlessly, then that's a bug. Please contact us right away so we can fix the (unintended) breaking changes.

Finally, run truffle compile --all

Running truffle compile will cause Truffle to upgrade your contract artifacts to the latest format. This will also unlock the debugging features so you can better inspect your contracts' behavior.

That's it! This process should be pretty smooth, but let us know if it's not.

Feedback

We know, this release is BIG. With it came some big changes, and we...

v3.4.6 – Gettin' Better

Hello! Some fresh Truffle updates for your Tuesday:

What's in this release

Improvements and upgrades. 💯

• Truffle now ships with Solidity v0.4.13 🎉 (#484)

• Migrations now show transaction ids of all attempted transactions so you can more easily diagnose finicky migrations. 🔍 (#495)

• We've made error reporting nicer so you can pull less hair out. (#489)

• You can now use aliases to run Truffle commands. No more RSI or knuckle pain! (#491)

  Examples:

  • truffle u == truffle unbox.
  • truffle com == truffle compile. (truffle c could match multiple commands, so it won't work)

• In your configuration file, you can now wrap network providers in a function so you're not pinging multiple networks all at once! (#348)

• Internal: We now use web3 v0.20.1 inside Truffle. Great work to that team. (#485)

Get the new version

First uninstall the old version of Truffle:

$ npm uninstall -g truffle

Then install the new version:

$ npm install -g truffle

If you're on Ubuntu or OS X, you may need to use sudo in the above commands.

Thanks!

As always, we thank you for your continued support and feedback. Keep a look out for plenty new features in the coming weeks, as we have a lot of exciting things to show.

Cheers!
-- The Truffle Team

v3.4.3 – A Box of Chocolates

Hey there!

We're pleased to announce a new command to get you started with Truffle even easier.

What's in this release

A new command: truffle unbox. You can use it to install example applications and boilerplate code -- dubbed, Truffle boxes -- to get your Truffle project started up and running quickly.

Read more about Truffle boxes on our blog.

Here's the new usage:

• truffle unbox <box name> to install official boxes
• truffle unbox <url> to install community-supported boxes (hat tip Status.im 🎉 )

What this means

Not only can you unpack one of our official boxes, and get an example dapp running via a single command, but anyone can publish a dapp configuration for others to use as well.

This also expands the dapps you can create. Each box can be configured to support whatever language and tools it's designed for, paving the way for Ethereum-enabled mobile projects, desktop applications, command line tools and more. 📱 💻

Get the new version

First uninstall the old version of Truffle:

$ npm uninstall -g truffle

Then install the new version:

$ npm install -g truffle

If you're on Ubuntu or OS X, you may need to use sudo in the above commands.

Thanks!

As always, we thank you for your continued support and feedback. Keep a look out for plenty new features in the coming weeks, as we have a lot of exciting things to show.

Cheers!
-- The Truffle Team

v3.3.0 - EPLS (easy peasy lemon squeezy)

Hi there! Once again, we have good news. 🎉

What's in this release

Installation issues are gone!

What we've been doing

If you've been following along, you'll know we've been working hard making installation much easier. No matter what platform you're on, in the past installation has been hard. And it's really a bummer: if you're trying to build an app, the last thing you want is to get stuck at the beginning.

Today, we've fixed all of those issues. Yep, all of them. Not one by one, and fix by fix; but instead we completely sidestepped the previous installation process that created the issues to begin with. The commands remain the same (see below) but has been much improved under the hood. You can find more information on our blog.

This version of Truffle, compared to v3.2, will look the same to you from a features standpoint, but it will now be easier to install, and all the previous installation dependencies are no longer required.

Get the new version

First uninstall the old version of Truffle:

$ npm uninstall -g truffle

Then install the new version:

$ npm install -g truffle

If you're on Ubuntu or OS X, you may need to use sudo in the above commands.

Thanks!

As always, we thank you for your continued support and feedback. Keep a look out for plenty new features in the coming weeks, as we have a lot of exciting things to show.

Cheers!
-- Tim and the Truffle Team

v3.2.2 - upgrade Solidity to v0.4.11

This release upgrades the version of Solidity bundled with Truffle to v0.4.11. 🎉

Big thanks to the Solidity team for squashing issues and keeping solidity awesome.

v3.2.1 - upgrade web3 to 0.18.2

This is a small followup to the last release that upgrades web3 to 0.18.2 for your contract abstractions. This introduces a very small breaking change where your abstractions will fail to deploy contracts that selfdestruct within their constructor. Since this is a very minor breaking change and will effect very little of you, we chose to release it as a minor version bump (3.2.0 -> 3.2.1). If this affects any of you, don't hesitate to contact us in our Gitter channel

Cheers!

v3.2.0 - Features, Bug Fixes, and Infrastructure

This is a broad release taking into account some feedback since the release of 3.0. We appreciate your involvement and love responding to your feature requests, questions and concerns. Keep 'em coming!

To install, first uninstall Truffle then reinstall to ensure the correct dependencies are updated:

$ npm uninstall truffle -g
$ npm install truffle -g

Note: We made a minor release after this one upgrading web3 to 0.18.2 due to request of our users. Truffle v3.2.1 is now the latest release.

Features

• More module separation. Biggest is demo code initialization. You can now use truffle init and truffle init webpack to download example code directly from github. Stay tuned for more examples!

• Huge speed improvements on initialization. Big thanks to @LogvinovLeon. #355

• You can now specify initial balances for Solidity tests. This will tell the test runner to send your test contracts some Ether upon initialization, which you can then send to your contracts to test how they respond. Read the documentation.

• You can now trigger fallback functions and send Ether directly to contracts via the truffle-contract abstractions: https://github.com/trufflesuite/truffle-contract#sending-ether--triggering-the-fallback-function

• The third parameter of a migration is now the list of available accounts provided by your Ethereum node and/or provider. i.e.,

  File: 2_deploy_contracts.js

  module.exports = function(deployer, network, accounts) {
    // ... deploy steps ...
  };

• Removed the restriction that contract names must match file names. 🎉 See trufflesuite/truffle-compile#3. See next bullet.

• Contracts can now be required via artifacts.require() using their name rather than their source file name. For example, let's review the following code:

  // same file: MyContracts.sol
  
  library SomeLibrary {...}
  
  contract SomeContract {...}

  You can "require" the artifacts for these contracts using the following within migrations and tests:

  var SomeLibrary = artifacts.require("SomeLibrary");
  var SomeContract = artifacts.require("SomeContract");

Bug Fixes

• truffle init will no longer initialize a project if an existing project is found in the current working directory. Fixes #356
• Events are output on test failure, as before. Thanks to @masonforest for the PR. Fixes #365
• Prevented truffle migrate from running files that didn't start with a number or were of the wrong extension. Fixes #353
• We've now left cyclic dependency checking to Solidity, since cyclic dependencies are only an issue in some circumstances, which Solidity handles. Fixes #135
• Solidity compilation warnings are now respected, and won't cause a compiler error. To ensure Truffle errors on warnings, use the --strict option during compilation. Fixes #296
• Javascript tests weren't being rerun when inside the Truffle console. That's now fixed. Fixes #325
• Migrations and scripts ran with truffle exec can now require global modules like fs. Fixes #255 & #259

Infrastructure

• solidity-parser has been updated to 0.3.0 to support inline assembly
• Added Travis CI integration to main Truffle project, as well as some modules. More modules slated for Travis CI integration soon.
• Added infrastructure for scenario tests that run Truffle just like you do.

Documentation

The documentation at http://truffleframework.com/docs will be updated shortly.

Thank you!

Big thank you to everyone involved with providing your feedback, feature requests and pull requests.

A new Truffle - v3.0.2

After a long wait, Truffle 3.0 is finally here! 🎉

⚠️ Warning: If you were using Truffle beta 3.0.0-9 or below, _do not immediately upgrade_. Read these release notes and the upgrade guide first.

Install

First uninstall your current version of Truffle then install the new one:

$ npm uninstall -g truffle
$ npm install -g truffle
$ truffle version # => 3.0.2

Features / Overview

Truffle 3.0 brings a lot to the table. It has been in the planning stages since July of last year, and the release marks our first successful launch through the Truffle Beta program. With 3.0, you get:

• Package Management through NPM and EthPM using the ERC190 standard (documentation)
• Unit tests written completely in Solidity alongside your Javascript tests (documentation)
• Better, more secure, more refined network management
• The truffle-contract contract abstraction, a successor to EtherPudding that gives you more control, better error handling, and granular, targeted event processing. (documentation)
• More integrations. See our note below about modularization. We're also working on an extension for Visual Studio
• Less opinions. Truffle now saves contract artifacts solely in JSON, meaning you can use Truffle to create smart-contract enabled applications alongside any other tool and language. We're even starting a schema to create a standard for saving network artifacts across tools. This schema is still very much a draft. Please contribute!

Under the hood, Truffle has undergone an advanced reorganization, and has been separated out into over 20 individual modules with more coming. This should make integrating with Truffle -- or using specific Truffle features -- easier within your complex, custom environment.

We also have a new dashboard that show's how Truffle is growing over time:

• http://truffleframework.com/dashboard

Before upgrading to Truffle 3.0, know that there are a lot of breaking changes, even if you're upgrading from Truffle beta 3.0.0-9. So be careful, and ensure you read the full list of breaking changes and associated documentation. 👍

Breaking Changes

With great power comes great responsibility (thanks Uncle Ben!). Truffle 3.0 gives you more power to write better smart contracts, but with it comes the responsibility of breaking changes. There were many breaking changes this release, so much so that we wrote you an upgrade guide to get you using Truffle 3.0 as quickly as possible. Give it a read, and let us know what you think.

Big Thanks

There are too many people to thank for this release. We have so many wonderful users and contributors that work to make Truffle -- and its community -- better everyday. Specifically, I'd like to thank @pipermerriam for spearheading the Ethereum Package Management effort and working hard to specify the ERC190 spec exactly. I'd also like to thank the folks at Dapple and Eris/Monax for contributing to make ERC190 and the Ethereum Package Registry a new standard.

Reach Out!

As with all releases, especially one as wide ranging as this, there's bound to be an issue or two. If you ever run into trouble, don't hesitate to ask questions in the Truffle Gitter channel or submit a new issue.

Thanks for your feedback, and happy coding!

v2.0.0: Tackling Complexity

Great news: I'm happy to announce the release of Truffle v2.0! 🎉

Install

First uninstall your current version of Truffle then install the new one:

$ npm uninstall -g truffle
$ npm install -g truffle 
$ truffle --version  # => 2.0.0

Changelog / New Features

The goal of Truffle 2.0 was to tackle complexity all across the application. The largest feature in this release is the addition of Migrations, which allow you to deploy complex applications with ease. Many other changes were under the hood, which resulted in significant decoupling of modules making them great for outside use. Be sure to check out our updated documentation for more information.

This version requires a lot of changes to project structure. To get familiar with the new version, consider starting a new project with truffle init before migrating your current project.

All notable changes, in bulleted list form:

• Migrations for complex deployments. This means the deploy configuration has been completely removed, in favor of a simple yet powerful migrations system.
• The concept of Environments has been removed and has been replaced by Networks.
• The Truffle console has been significantly improved.
• Now uses EtherPudding 3.0. This reduces complexity especially on your application's frontend, and no longer requires Pudding as a frontend dependency.
• Solidity imports are now relative to the contract that depends on those imports. Import paths must be prefixed by ./ or ../. All other imports will error.
• As mentioned, many changes under the hood. You can now use Truffle as a node dependency within your applications, and only use the modules you need.
• Many more upgrades and bug fixes.

Have Issues?

Check out our Truffle gitter to chat with the community. As well, you can always file an issue in the Truffle issues tracker.

-- Truffle team

Truffle 1.0.0!

Great news! Truffle 1.0.0 has been released which sees significant improvements across the board. In fact, the number of improvements were so great that instead of releasing v0.4.0 like we had planned, we jumped straight to v1.0.0. Our milestones set for v0.5.0 and v0.6.0 were quickly surpassed.

Here's the run down.

Install

First uninstall your current version of Truffle then install the new one:

$ npm uninstall -g truffle
$ npm install -g truffle 
$ truffle --version  # => 1.0.0

🎉 Now available on Windows, Linux and Mac!

Node v5.x recommended.

New Features

• Tons better documentation. You can see our full set of docs at http://truffle.readthedocs.org.
• Full Windows support. You can use the above install instructions to use Truffle on Windows, too! And Truffle's sister application, ethereumjs-testrpc, works great on Windows as well!
• The newest Solidity. Solidity 0.3.0 support comes standard.
• Library linking. Truffle will automatically link your libraries, no questions asked.
• Smart compliation. No need to recompile contracts that haven't been changed. Time, saved.
• Modular build system. Swap in your own build system and deeply integrate it with Truffle. See our build processes documentation for more details.
• Smart configuration files. Instead of JSON, use Javascript to configure your project by renaming truffle.json into truffle.js. And even better, all your environments' config.json files can be renamed to config.js as well. (Hello new world!)

And much much more. See v0.4.0 for a more detailed breakdown of changes and additions.

Have Issues?

Check out our Truffle gitter to chat with the community. As well, you can always file an issue in the Truffle issues tracker.

Special Thanks

Special thanks to all who helped test the v0.4.0 pre-release (now v1.0.0) and everyone who contributed code and reported issues. Cheers!

-- Truffle team