Updated help for errors (#2489).

Author: ricmoo

docs.wrm/troubleshooting/building.wrm

@@ -0,0 +1,15 @@
+_section: Building @<troubleshooting-building>
+
+@TODO
+
+_subsection: Packages
+
+Sometimes packages get out of sync.
+
+_code:
+
+/home/ethers> rm package-lock.json node_modules/
+
+/home/ethers> rm yarn.lock
+
+/home/ethers> npm install

docs.wrm/troubleshooting/errors.wrm

@@ -0,0 +1,249 @@
+_section: Error Codes @<error-codes>
+
+All errors in ethers are created by the [[Logger]] class, which includes
+a number of additional properties and extra data, which can assist in
+debugging and when submitting issues.
+
+When submitting an issue, please include as much of any error as possible,
+but also make sure you understand the error and have tried suggested solutions
+both in this trouble-shooting document and any other issues you find when
+searching the GitHub issues.
+
+
+_subsection: CALL_EXCEPTION @<help-CALL_EXCEPTION>
+
+This error occurs when a call or transaction is used to interact with
+the blockchain reverts (via ``revert``, ``require``, et cetera).
+
+Due to the overall flexibility of Ethereum and Turing Completeness,
+there is a large variety of reasons this can occur and troubleshooting
+requires attention.
+
+
+_heading: Common Causes
+
+- The code does not exist on-chain. This may happen if you failed to wait
+  until the contract was deployed, the address is incorrect or if you
+  are connected to a different network than the contract has been deployed.
+  Check the code exists using ``provider.getCode(address)``.
+- The wrong code is being accessed, for example if an artifact file was
+  not correctly updated so an older instance of the contract is being called
+- The contract is failing during a ``require`` statement. For example, if
+  a contract method requires an //admin account// to be used, but the
+  contract is connected to another [[Signer]].
+- The wrong ABI is being used to interact with a contract.
+
+_heading: Debugging
+
+- Always double check the address and network you are connected to and use
+  ``provider.getCode(address)`` to verify the deployed code matches your
+  most recent version.
+- Try accessing other, simpler contract methods to verify the account is correct.
+
+
+_subsection: INSUFFICIENT_FUNDS @<help-INSUFFICIENT_FUNDS>
+
+This usually occurs when a transaction is attempted, but the sending account
+does not have enough ether to cover the cost of the transaction.
+
+A transaction has an intrinsic cost which must be met, which accounts for
+the value being sent, the base fee of the transaction, additional fees per byte
+of calldata and whether the transaction will create a new account (i.e. the ``to``
+is empty).
+
+This error can also happen if ``provider.estimateGas`` is used with a non-zero
+fee (i.e. ``gasPrice``, ``maxFeePerGas`` or ``maxPriorityFeePerGas``). If any
+fee properties are specified, the ``from`` account must have sufficient ether
+to execute the transaction.
+
+
+_subsection: MISSING_NEW @<help-MISSING_NEW>
+
+Classes in ethers must be instantiated with the ``new`` operator. This
+error indicates that a Class is attempting to be used as a function.
+
+_code: Examples @lang<javascript>
+
+//_hide: privateKey = "0x0123456789012345678901234567890123456789012345678901234567890123";
+//_hide: Wallet = ethers.Wallet;
+
+// Bad:
+//_throws:
+ethers.Wallet(privateKey)
+//_log:
+
+// Good:
+//_result:
+new ethers.Wallet(privateKey)
+//_log:
+
+
+_subsection: NONCE_EXPIRED @<help-NONCE_EXPIRED>
+
+This error occurs when a transaction is being sent with a ``nonce`` that
+is lower than next required ``nonce``.
+
+Each Ethereum transaction requires a ``nonce`` property equal to the index
+of that transaction for that account for all time. So, if an account has
+send four transactions over its lifetime, that means the nonces 0 though 3
+(inclusive) have been used. The next transaction must use a nonce of 4.
+Attempting to re-use a nonce less than 4 will result in this error.
+
+
+_subsection: NUMERIC_FAULT @<help-NUMERIC_FAULT>
+
+A [numeric fault](errors--numeric-fault) is a consequence of
+performing an illegal operation with numeric values, such as
+dividing by zero.
+
+The error will indicate the ``operation``, which further indicates
+the reason for the error.
+
+
+_heading: Overflow @<help-NUMERIC_FAULT-overflow>
+
+JavaScript uses [IEEE 754 double-precision binary floating point](link-wiki-ieee754)
+numbers to represent numeric values. As a result, there are //holes//
+in the integer set after 9,007,199,254,740,991; which is
+problematic for //Ethereum// because that is only around 0.009
+ether (in wei), which means any value over that will begin to
+experience rounding errors.
+
+As a result, any attempt to use a number which is outside the safe
+range, which would result in incorrect values, an error is thrown.
+
+In general, numbers should be kept as strings, [[BigNumber]] instances or
+using ES2020 bigints, which all can safely be used without loss of precission.
+
+_code: Examples @lang<javascript>
+
+// One ether is outside the safe range
+//_throws:
+BigNumber.from(1000000000000000000)
+//_log:
+
+// Providing the value as a string is safe
+//_result:
+BigNumber.from("1000000000000000000")
+//_log:
+
+// As is using a bigint (notice the `n` suffix)
+//_result:
+BigNumber.from(1000000000000000000n)
+//_log:
+
+// But most often, the `parseEther` function solves this
+//_result:
+utils.parseEther("1.0")
+//_log:
+
+
+_heading: Numeric Underflow @<help-NUMERIC_FAULT-underflow>
+
+Numeric underflow sbould not be confused with overflow.
+
+Numeric underflow occurs when the precission of a value cannot be
+safely represented in the current data type.
+
+**Common Causes**
+
+- Using values with fractional componets (e.g. ``BigNumber.from(1.2)``).
+  If you require fractions, you must use the [[FixedNumber]] class.
+- Parsing string values that have more decimals than the unit supports
+  (e.g. ``parseUints("1.33", 1)``).
+
+_code: Examples @lang<javascript>
+
+// BigNumbers cannot be created with a fractional component
+//_throws:
+BigNumber.from(1.2)
+//_log:
+
+// Parsing a value with more decimals than the type
+//_throws:
+utils.parseUnits("1.34", 1);
+//_log:
+
+
+_heading: Division by zero @<help-NUMERIC_FAULT-division-by-zero>
+
+This error occurs when dividing by zero or attempting to take the modulo zero.
+
+
+_heading: Unbound Result @<help-NUMERIC_FAULT-unbound-result>
+
+The ethers [[BigNumber]] does not support bitwise operators
+on negative numbers which can result in the need for an infinite
+number of set bits.
+
+Other implementations may use negative values to indicate this,
+but this is considered out of scope for ethers.
+
+
+_heading: Unsupported Operation @<help-NUMERIC_FAULT-unsupported>
+
+The ethers [[BigNumber]] does not support negative powers or bitwise
+shift operation using negative values.
+
+_code: Examples @lang<javascript>
+
+two = BigNumber.from(2);
+
+//_throws:
+two.pow(-2)
+//_log:
+
+// Cannot use negative values to alter shift direction
+//_throws:
+two.shr(-1)
+//_log:
+
+
+_subsection: REPLACEMENT_UNDERPRICED @<help-REPLACEMENT_UNDERPRICED>
+
+To prevent nodes from being overloaded with junk transactions, a transaction
+is only accepted into the memory pool if it has a reasonable chance of being
+actually mined, which means that the account has sufficient balance, the nonce
+is correct and the fee seems reasonable.
+
+Once a transaction is in the memory pool though, to prevent an account from
+flooding the network with many different transactions with the same nonce (each
+of which satisfies the above criteria), to replace an existing transaction
+an additional committment of a fee must be made by increasing the promised fee.
+
+When replacing a legacy non-EIP1559 transaction, the ``gasPrice`` must be
+increased. When replacing a modern, EIP-1559 transaction, the ``maxPriorityFeePerGas``
+should be increased.
+
+
+_subsection: TRANSACTION_REPLACED @<help-TRANSACTION_REPLACED>
+
+This error is thrown when waiting for a transaction which has been
+replaced by another, by the sender submitting a second transaction
+with the same nonce, while the transaction was pending in the
+transaction pool.
+
+You can learn more about this feature in the ``.wait`` method of
+[TransactionResponse](providers-TransactionResponse).
+
+
+_subsection: UNPREDICTABLE_GAS_LIMIT @<help-UNPREDICTABLE_GAS_LIMIT>
+
+During gas estimation it is possible that a transaction would actually
+fail (and hence has no reasonable estimate of gas requirements) or that
+the transaction is complex in a way that does not permit a node to
+estiamte the gas requirements, in which case this error is thrown.
+
+In almost all cases, this will unfortunately require you specify an
+explicit ``gasLimit`` for your transaction, which will disable ether's
+automatic population of the ``gasLimit`` field, which will cause this
+error to go away.
+
+To dial in an appropriate gas limit, try a value that is much higher
+than you expect, and then make a few transactions to discover reasonable
+values and then you can reduce this value down to that ballpark.
+
+Keep in mind this error can also occur if the transaction would
+legitimately fail, in which case the root cause must be addressed, such
+as ensuring the correct [[Signer]] is being used, the appropriate allowance
+for an ERC-20 token has been approved, etc.

docs.wrm/troubleshooting/help.wrm

@@ -0,0 +1,62 @@
+_section: Getting Help @<troubleshooting-issues>
+
+@TODO
+
+_subsection: Starting a discussion
+
+Before opening an issue
+
+
+_subsection: Opening an Issue
+
+Keep in mind that opening an issue should be a last resort, as it
+requires time and energy by the library developers to look at that
+could otherwise be spent on improving the library, documentation
+and tools.
+
+Before opening an issue, please make sure you have searched any
+public information, such as:
+
+- Documentation
+- GitHub Discussions
+- GitHub Issues (including closed issues)
+
+There are several types of issues tracked by ethers. Using the correct
+one helps you receive feedback quicker and helps us keep the right
+person 
+
+_heading: Feature Requests
+
+
+
+_heading: Bugs
+
+This type of issue is for anything you you believe to be a bug in ethers.
+
+Keep in mind that ethers is used extensively by thousands of people every
+day, so while chances are possible you found a bug, please make sure to
+do your due diligence to rule out user error.
+
+If you are new to ethers, or are doing a fairly common operation, it is
+quite likely what you are experiencing is a misunderstanding of how to
+use a function, method or class. You should consider opening a discussion first.
+
+
+Please make sure you include as much information as is useful:
+
+- Are you using a third-party library, like Hardhat or Truffle?
+- What platform are you on, a web browser, React Native, node, etc.?
+- What network are you on, such as Ethereum mainnet, Optimism, etc.?
+- What backend are you using, such as Geth, INFURA, Provider Engine, etc.?
+
+
+_heading: Docuementation
+
+If you have found a typo in the documentation, a feature which isn't
+documented (or documented well) or just find something described in
+the documentation confusing, please feel free to create an issue and
+we will try to improve it.
+
+_heading: Other
+
+This should never be used.

docs.wrm/troubleshooting/index.wrm

@@ -0,0 +1,11 @@
+_section: TroubleShooting
+
+
+
+_toc:
+    building
+    errors
+    networks
+    help
+
+_subsection: About Trbouble-Shooting

docs.wrm/troubleshooting/network.wrm

@@ -0,0 +1,9 @@
+_section: Troubleshooting Network @<troubleshooting-network>
+
+@TODO
+
+_subsection: Links
+
+_subsection: Cross-Origin Resource Sharing (CORS)
+
+_subsection: Mobile Development (Device Firewalls)

packages/logger/src.ts/index.ts

@@ -250,7 +250,7 @@ export class Logger {
         }
 
         if (url) {
-            message += " [ See: https:/\/ethers.org/errors/" + url + " ]";
+            message += " [ See: https:/\/links.ethers.org/v5-errors-" + url + " ]";
         }
 
         if (messageDetails.length) {