-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Conversation
I hope there's a trick to still have BigNumbers returned in case of numbers |
@rudolfix So far the only trick I have is making strings have a What do you advise? |
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is fabulous @cgewecke!
Here's some notes that are mostly polish-level things. Let me know what I can help out with, so you don't have to implement all my pedantry yourself.
release.md
Outdated
|
||
## 1. All SOLC. | ||
|
||
It's now possible to have truffle compile with: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Truffle
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The all capped now.
release.md
Outdated
⚠️ **Early draft. Details subject to change.** ⚠️ | ||
|
||
# 🐘 🐘 V5 🐘 🐘 🐘 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(just a reminder: we'll need a preamble.)
release.md
Outdated
|
||
# 🐘 🐘 V5 🐘 🐘 🐘 | ||
|
||
## 1. All SOLC. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's remove the indexes for these headers, and instead have a table of contents at the top. There's a lot here. It'd be nice to lay it all out upfront.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah very good idea!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Put a small TOC in but it doesn't scroll - not sure if it's because it's in a comment or the links are bad. Probably need to work on this in the release context.
release.md
Outdated
``` | ||
|
||
### Advanced: | ||
+ docker |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
note for full release: this a great list of things we'll have to remember to document. Making an issue for full-relesae checklist #1176 so we can add stuff as we think of it.
"test": "truffle compile && truffle test" | ||
``` | ||
|
||
Many thanks to the Solidity team for making all of the above possible and for their helpful advice over the last year. 🙌 🙌 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I second this ------------------------------------------^
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That second pair of hands is yours!
release.md
Outdated
|
||
### Methods / `.new` have an EventEmitter interface *and* return a promise. | ||
```javascript | ||
example |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For these examples, I think it's helpful to include a line above:
const example = await artifacts.require("Example").deployed();
Well, maybe not, because that kind of clashes with the .then()
syntax we're showing off.
Wait, is this now possible?:
let receipt = await example
.setValue(123)
.on('transactionHash', hash => {})
/* ... */
.on('confirmation', (num, receipt) => {} )
Anyway, my point is that it's probably worth showing a more complete example so there's literally no guesswork.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mmm. Yeah I could go either way - I think I had it as you've shown it originally but when I looked at the web3 docs they used the then
which seemed clearer.
Like there's also a weird temporal thing about lines above happening before lines below. In the receipt example - receipt resolves after the txHash fires and that seemed weird to me.
Am I crazy lol?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added the require.
```javascript | ||
example | ||
.ExampleEvent() | ||
.on('data', event => ... etc ... ) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As I am reading this, I am getting giddy.
assert(err.reason === 'not authorized'); | ||
assert(err.message.includes('not authorized'); | ||
} | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This can be broken up:
Solidity:
require(msg.sender == owner, 'not authorized');
Javascript:
try {
await example.transferToSelf({from: nonOwner})
} catch (err) {
assert(err.reason === 'not authorized');
assert(err.message.includes('not authorized');
}
Maybe not bold?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah that's much better.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
release.md
Outdated
``` | ||
|
||
### Configure format of number return values | ||
As mentioned above - `truffle-contract` now returns BN. We've made this configurable so if you have an existing test suite you'd prefer to gradually transition from BigNumber to BN, it's possible to configure a contract's number format as below. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
BigNumber.js
etc.
Maybe these should be links; or maybe we should just make sure everything gets linked at least once.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
truffle(development)> balance.toNumber() | ||
20000 | ||
truffle(development)> | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We'll likely need:
- Contributing section / Call for feedback to get everything perfect for the full release
- Thank you to our awesome community
- Installation instructions
![migrate-rinkeby](https://user-images.githubusercontent.com/7332026/43867960-3499922c-9b20-11e8-8553-589308a6cd61.gif) | ||
|
||
**More migrations improvements are coming soon...**. | ||
+ cag from Gnosis has written a really nice addition to the Migrations module that will automatically deploy contract dependencies you've installed with `npm` along with your own contracts. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh missed this: we should @cag
him.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes - and there's one for elena as well above - didn't want to actually at them for the draft but definitely try make sure we don't forget this.
General thought on naming: I like |
@gnidan Please just edit at will - whatever changes you want to make are good. I'll go through your suggestions though and fix those up. Thanks for reviewing :) |
Have ended up mixing v5 / V5. There are some cases (like headings and where it appears at the beginning of a sentence where the lower case looks weird to me but please change this to whatever you prefer. Web3 is referred to initially as Web3.js and afterwards Web3 (I think the |
In the release notes, you have this:
We probably shouldn't encourage the use of absolute paths here, and we might want to remove support for absolute paths here entirely. If an absolute path is stored in the |
PS: Love the emojis. 👏 💃 🌮 |
@tcoulter Ok cool, I'll change that example to something 'workspacey'. |
- Add explicit anchors - Remove 80-character line breaks
This is released! |
DO NOT MERGE - this is here so people can do review stuff to it if they want to.
Good day! We're pleased to announce the first beta release of Truffle v5. With this release, we're excited to bring you some new features and improvements that will make your life easier.
What's included, you ask? Well, get ready to use whatever Solidity version you want (Truffle will even automatically download it for you.) Or how about an improved migrations system, which dry-runs by default and provides lots of information to understand what is going right or wrong. Maybe you've been waiting for Web3.js 1.0. Perhaps you're sick of typing
.then()
and want to useawait
in the console. Truffle v5 has all of this, and more!If you're as excited as we are and can't wait, here's how to upgrade:
Or keep reading for more information!
Release Contents
.new
have an EventEmitter interface and return a promise.defaultBlock
parameter..new
Bring your own compiler
It's now possible to have Truffle compile with:
List available versions at the command line
Specify a solcjs version
Set the compilers solc
version
key to the one you'd like. Truffle will fetch it from the solc-bin server and cache it in your local evironment.Advanced
path/to/solc
Docker images should be installed locally by running:
truffle.js
Speed comparison
Docker and native binary compilers process large contract sets faster than solcjs. If you're just compiling a few contracts at a time, the speedup isn't significant relative to the overhead of running a command (see below). The first time Truffle uses a docker version there's a small delay as it caches the solc version string and a solcjs companion compiler. All subsequent runs should be at full speed.
Times to
truffle compile
on a MacBook Air 1.8GHz, Node 8.11.1For help installing a natively built compiler, see the Solidity docs here.
Contract Profiling
Truffle has always tried figure out which contracts changed recently and compile the smallest set necessary (with varying degrees of success). It now does this reliably so you may benefit from setting up an
npm
convenience script that looks like this:Many thanks to the Solidity team for making all of the above possible and for their helpful advice over the last year. 🙌 🙌
🐇 🐇 Web3.js 1.0 🐇 🐇
truffle-contract now uses Web3.js 1.0 under the hood. It's nice! The error handling (especially the parameter checking) is really good. And there's lots of new work happening over there - ENS support is being added and EthPrize is funding an API to make contract packages published to EthPM easily available as well.
We've tried to minimize the inconvenience involved in transitioning an existing test suite from Web3 0.x to 1.0. Unfortunately there are some breaking changes due to differences in the way Web3 1.0 formats outputs (see chart below).
The biggest of these is that truffle-contract now returns numbers as BN by default instead of BigNumber. This is necessary - BigNumber doesn't have the precision required by the EVM. The number libraries share some methods (notably
.toNumber()
) but their arithmetic operations are quite different.Important: If you receive a number directly from Web3 (e.g. not from a truffle-contract instance) you'll get a string. Luckily there's a helpful BN conversion method in the Web3 utils.
Helpful Resources
.contract
(underlying Web3 abstraction).at
(TruffleContract method)🍨 Features 🍨
Methods /
.new
have an EventEmitter interface and return a promise.Events have an EventEmitter interface
Reason strings!! Find out the reason.
Solidity
Javascript
Overloaded Solidity methods (credit to @rudolfix and @mcdee)
Configure number return format
As mentioned above - truffle-contract now returns BN. We've made this configurable so if you have an existing test suite you'd prefer to gradually transition from BigNumber to BN, it's possible to configure a contract's number format as below.
Call methods at any block using the
defaultBlock
parameter.Automated fueling for method calls and deployments.
Contract deployments & transactions allowed to take as long as they take
Gas estimation for
.new
Config
To take advantage of the
confirmations
listener and to hear Events using.on
or.once
, you'll need to enable websockets in your network config as below.🐦 🐦 New Migrations 🐦 🐦
Deploying contracts to public networks is hard ... 🙂 The topic dominates our 10 most visited GitHub issues. On the bright side, those discussion threads are a rich trove of advice and brilliant insight from experienced Truffle users. V5 includes a rewrite of the
migrations
command that tries to integrate all their hard won knowledge into an easier to use deployment manager.Features
--interactive
flag at the command line to get a prompt between your dry run and real deployment.Configuration and use
Example network config
Example Migration using async / await
Deploying to Rinkeby...
More migrations improvements are coming soon....
npm
along with your own contracts.migrations
command is now completely evented and managed by a reporter module. Those hooks will be exposed so anyone can write a UI for it and hopefully you'll be plugging into ever more sophisticated deployment script managers soon. Work on the default UI to make it more interactive and colorful is ongoing.Even More!
truffle-console now supports async/await
A small but decisive improvement that should make the console much easier to use.
Example
External compiler support
For more advanced use cases, let's say your smart contract development workflow involves more than just compiling Solidity contracts. Maybe you're writing eWASM precompiles or making a two-dimensional
delegatecall
proxy. Or maybe you would just rather use @pubkey's solidity-cli instead of Truffle'ssolc
configuration.This is now supported by adding a
compilers.external
object to your Truffle config:When you run
truffle compile
, Truffle will run the configuredcommand
and look for contract artifacts specified bytargets
.This new configuration supports two main use cases:
Credit to @axic for the idea and for helping to hone our requirements as we implemented it. Thank you!
Target generated artifacts
If your compilation command generates artifacts directly, or generates output that contains all the information for an artifact, configure a target as follows:
Truffle will expand the glob (
*
) and find all.json
files in the listed path and copy those over as artifacts in thebuild/contracts/
directory.Post-processing artifacts
The above use case might not be sufficient for all use cases. You can configure your target to run an arbitrary post-processing command:
This will run
./process-artifact
for each matched.json
file, piping the contents of that file as stdin. Your./process-artifact
command is then expected to output a complete Truffle artifact as stdout.Want to provide the path as a filename instead? Add
stdin: false
to your target configuration.Target individual artifact properties
The other way to configure your external compilation is to specify the individual properties of your contracts and have Truffle generate the artifacts itself:
Specify
properties
and/orfileProperties
, and Truffle will look for those values when building the artifacts.These two approaches aim to provide flexibility, aiming to meet whatever your compilation needs may be.
Debugger mapping support
Mappings are now supported in truffle-debugger. Truffle will keep track of known mapping keys and let you inspect your contract's
mapping
variables with thev
command. What's more, this means you can inspectmapping
s ofstruct
s andstruct
s ofmapping
s, etc.!Acknowledgements
We'd like to extend a huge thank you to our community, our users, and our contributors, who have all been instrumental in helping us get this this point. We hope you enjoy this beta and all of Truffle's new features.
Please let us know if you find any problems or have any suggestions for making this release better. 🙇