Many doc issues related to calling a state-changing contract method with MetaMask

Sorry in advance for the second instalment of this rant, the first being at EthLondon where @ricmoo bore it with exceptionally good grace (especially considering it was something like 4am and he took time out from hacking on his own project to listen to feedback - although that didn’t even stop him winning a top prize…)

I kind of expected calling a smart contract to be the number 1 most popular use case for a library like this, and consequently I expected it would be the easiest thing to figure out from the documentation. I also heard that ethers.js was easier to use than web3.js (which I’ve never tried). Unfortunately so far I’ve found it to be extremely hard, and I’m not exactly a novice programmer, so there is definitely room for improvement.

My quest was to use ethers.js to call a non-constant smart contract method via Metamask. Nothing more complicated than that. Here are some of the things I struggled with on that quest:

• The Cookbook section comes after the API and low-level API sections. That’s completely the wrong way around. Docs should start with the simple stuff which 80% of people want to know, and then gradually get further into the weeds later on. Consequently I didn’t even notice the Cookbook section for a while because I was wading through the earlier sections assuming they would have what I needed.

• As suggested at EthLondon, the Cookbook section should be split into 1. the most common use cases (which should probably then be moved under “Getting Started”), and 2. the more obscure use cases like React Native. The latter probably belongs either just before or after the API section, but probably before the low-level API section which I’m guessing would be even less commonly needed.

• Subsections like “Calling a read-only Constant Method” and “Calling a Non-Constant Method” are buried under API > Contracts > Connecting to Existing Contracts > Connecting to a Contract. That’s at least one level too deep. Also, conceptually the word “connecting” has connotations of establishing some session over TCP/IP or that kind of thing. You don’t “connect” to a function, you call it. And indeed the word “calling” is what I’ve heard most used in the community for this meaning. “Invoking” would also be fine. Again, calling smart contracts is such a key use case for this library that it should have its own high-level (though not necessarily top-level) section, e.g. “Calling Smart Contracts”.

• “Waiting for Deployment” is not under “Deploying a Contract” - confusing.

• The API section has “Wallets and Signers”, “Providers”, then “Contracts” which in turn has a subsection “Providers vs. Signers” - confusing.

• https://docs.ethers.io/ethers.js/html/api-contract.html has a section called “Prototype” - confusing.

• As far as I can tell, the Javascript in https://docs.ethers.io/ethers.js/html/cookbook-contracts.html#return-a-value-from-a-state-changing-method is actually wrong, because it assigns to wallet:

    const wallet = new Wallet(privateKey, provider)
  

  but then never uses it?! But even if it did, how do I get the private key from Metamask? Maybe the answer to this particular riddle is hidden under a completely part of the docs: “Calling a Non-Constant Method” under “Connecting to Existing Contracts”, which as mentioned above is hard to find? Eventually I spotted:

    // Create a new instance of the Contract with a Signer, which allows
    // update methods
    let contractWithSigner = contract.connect(wallet);
  

  Perhaps this is the missing link between wallets and how to sign transactions invoking non-constant methods? But I still don’t see how to get the wallet object from MetaMask.

• Use of MetaMask is very common, therefore explanations of how to interface with it should be generally more prominent. Currently it’s buried in easy-to-miss places like https://docs.ethers.io/ethers.js/html/cookbook-providers.html#metamask. OK, so it explains how to get a signer. But now how do I use that signer to call a contract call? Maybe the “Signing Messages” section of the cookbook helps? Hmm, nope, that’s nothing to do with contract calls. Maybe under https://docs.ethers.io/ethers.js/html/api-wallet.html#signing ? Nope, also nothing to do with contract calls. Maybe https://docs.ethers.io/ethers.js/html/api-wallet.html#signer-api ? Nope, not there either.

So after all this, I still haven’t figured it out. If I had any hair I’d be tearing it out over this 😉 Again sorry for the rant, really hoping you can take this as constructive criticism which helps improve the docs. IIRC there is a new 5.x release already in the works which has some great improvements.

[aspiers]

@ricmoo commented on April 18, 2020 10:38 AM:

Oh, you just mean a normal state changing method? You just call it. 😃

I knew that was the intention, and I already had that working for read-only methods. But it was not obvious how incorporate the signer in order to use MetaMask to sign state-changing transactions.

const provider = new ethers.provider.Web3Provider(window.ethereum);
const signer = provider.getSigner();
const abi = [
    "function getBalance(address owner) view returns (uint)",
    "function transfer(address to, uint amount)"
];
const contract new ethers.Contract(address, abi, signer);

OK great, so the third argument to the Contract constructor (providerOrSigner) is the simple trick I was missing.

I’ll be including these types of examples in the new docs in the getting started section. 😃

Awesome, thanks 😃 I hope you can take account of my several other suggestions above too.

[ricmoo]

I just skimmed through this quickly, and think the current documentation addresses most of this, so I’m going to close it.

But I would love another pass, browsing the documentation, and adding any new comments you have. Feel free to open another issue.

Thanks! 😃