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 couldn't keep putting out great software without your help. So please: Get on the bat phone (our Truffle Gitter channel) and drop us a line. We'd love to hear your experiences with this new release, how it makes your development life better, and how we can continue to improve.

Thanks as always, and happy coding!

-- The Truffle Team