docs: better linking to errors in docs

ricmoo · ricmoo · commit f0a88f551f5c · 2021-02-04T18:59:51.000-05:00
diff --git a/docs.wrm/api/utils/address.wrm b/docs.wrm/api/utils/address.wrm
@@ -45,13 +45,13 @@ _property: ethers.utils.getAddress(address) => string<[[address]]>  @<utils-getA
 Returns //address// as a Checksum Address.
 
 If //address// is an invalid 40-nibble [[HexString]] or if it contains mixed case and
-the checksum is invalid, an InvalidArgument Error is thrown.
+the checksum is invalid, an [INVALID_ARGUMENT](errors--invalid-argument) Error is thrown.
 
 The value of //address// may be any supported address format.
 
 _property: ethers.utils.getIcapAddress(address) => string<[IcapAddress](address-icap)>  @<utils-getIcapAddress> @SRC<address>
 Returns //address// as an [ICAP address](link-icap).
-Supports the same restrictions as [utils.getAddress](utils-getAddress).
+Supports the same restrictions as [getAddress](utils-getAddress).
 
 _property: ethers.utils.isAddress(address) => boolean  @<utils-isAddress> @SRC<address>
 Returns true if //address// is valid (in any supported format).
diff --git a/docs.wrm/api/utils/logger.wrm b/docs.wrm/api/utils/logger.wrm
@@ -48,47 +48,46 @@ Throw an Error with //message// and an optional //code// and
 additional //params// set.
 
 _property: logger.throwArgumentError(message, name, value) => never @SRC<logger>
-Throw an [INVALID_ARGUMENT](errors-InvalidArgument) Error with //name// and //value//.
-
+Throw an [INVALID_ARGUMENT](errors--invalid-argument) Error with //name// and //value//.
 
 _heading: Usage Validation
 
 There can be used to ensure various properties and actions are safe.
 
-_property: logger.checkAbstract(target, kind) => void @SRC<logger>
-Checks that //target// is not //kind// and performs the same operations
-as ``checkNew``. This is useful for ensuring abstract classes are not
-being instantiated.
+_property: logger.checkAbstract(target, kind) => void @<Logger-checkAbstract> @SRC<logger>
+If //target// is //kind//, throws a [UNSUPPORTED_OPERATION](errors--unsupported-operation) error
+otherwise performs the same operations as [checkNew](Logger-checkNew).
+
+This is useful for ensuring abstract classes are not being instantiated.
 
-_property: logger.checkArgumentCount(count, expectedCount [ , message) => void @SRC<logger>
-If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](errors-MissingArgument)
-or [UNEXPECTED_ARGUMENT](errors-UnexpectedArgument) error.
+_property: logger.checkArgumentCount(count, expectedCount [ , message) => void @<Logger-checkArgumentCount> @SRC<logger>
+If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](errors--missing-argument)
+or [UNEXPECTED_ARGUMENT](errors--unexpected-argument) error.
 
-_property: logger.checkNew(target, kind) => void @SRC<logger>
+_property: logger.checkNew(target, kind) => void @<Logger-checkNew> @SRC<logger>
 If //target// is not a valid ``this`` or ``target`` value, throw a
-[MISSING_NEW](errors-MissingNew) error. This is useful to ensure
+[MISSING_NEW](errors--missing-new) error. This is useful to ensure
 callers of a Class are using ``new``.
 
-_property: logger.checkNormalize(message) => void @SRC<logger>
+_property: logger.checkNormalize(message) => void @<Logger-checkNoralize> @SRC<logger>
 Check that the environment has a correctly functioning [[link-js-normalize]]. If not, a
-[UNSUPPORTED_OPERATION](errors-UnsupportedOperation) error is thrown.
+[UNSUPPORTED_OPERATION](errors--unsupported-operation) error is thrown.
 
-_property: logger.checkSafeUint53(value [, message ]) => void @SRC<logger>
+_property: logger.checkSafeUint53(value [, message ]) => void @<Logger-checkSafeUint53> @SRC<logger>
 If //value// is not safe as a [JavaScript number](link-wiki-ieee754), throws a
-[NUMERIC_FAULT](errors-NumericFault) error.
-
+[NUMERIC_FAULT](errors--numeric-fault) error.
 
 _heading: Censorship @<Logger--censorship>
 
-_property: Logger.setCensorship(censor [ , permanent = false ]) => void @SRC<logger>
+_property: Logger.setCensorship(censor [ , permanent = false ]) => void @<Logger-setCensorship> @SRC<logger>
 Set error censorship, optionally preventing errors from being uncensored.
 
 In production applications, this prevents any error from leaking information
 by masking the message and values of errors.
 
 This can impact debugging, making it substantially more difficult.
 
-_property: Logger.setLogLevel(logLevel) => void @SRC<logger>
+_property: Logger.setLogLevel(logLevel) => void @<Logger-setLogLevel> @SRC<logger>
 Set the log level, to suppress logging output below a [particular log level](Logger-levels).
 
 
@@ -98,86 +97,126 @@ Every error in Ethers has a ``code`` value, which is a string that will
 match one of the following error codes.
 
 
-_heading: Generic Error Codes
+_heading: Generic Error Codes @<errors-generic>
 
-_property: Logger.errors.NOT_IMPLEMENTED
-The operation is not implemented.
+_property: Logger.errors.NOT_IMPLEMENTED @<errors--not-implemented>
+The operation is not implemented. This may occur when calling a method
+on a sub-class that has not fully implemented its abstract superclass.
 
-_property: Logger.errors.SERVER_ERROR
+_property: Logger.errors.SERVER_ERROR @<errors--server-error>
 There was an error communicating with a server.
 
-_property: Logger.errors.TIMEOUT @<errors-Timeout>
+This may occur for a number of reasons, for example:
+
+- a [CORS](link-cors) issue; this is quite often the problem and also the
+  hardest to diagnose and fix, so it is very beneficial to familiarize
+  yourself with CORS; some backends allow you configure your CORS, such as
+  the geth command-line or conifguration files or the INFURA and Alchemy
+  dashboards by specifing allowed Origins, methods, etc.
+- an SSL issue; for example, if you are trying to connect to a local node via
+  HTTP but are serving the content from a secure HTTPS website
+- a link issue; a firewall is preventing the traffic from reaching the server
+- a server issue; the server is down, or is returning 500 error codes
+- a backend DDoS mitigation proxy; for example, Etherscan operates behind a
+  Cloudflare proxy, which will block traffic if the request is sent via
+  specific User Agents or the client fingerprint is detected as a bot in some
+  cases
+
+_property: Logger.errors.TIMEOUT @<errors--timeout>
 A timeout occurred.
 
-_property: Logger.errors.UNKNOWN_ERROR @<errors-UnknownError>
+_property: Logger.errors.UNKNOWN_ERROR @<errors--unknown-error>
 A generic unknown error.
 
-_property: Logger.errors.UNSUPPORTED_OPERATION @<errors-UnsupportedOperation>
+_property: Logger.errors.UNSUPPORTED_OPERATION @<errors--unsupported-operation>
 The operation is not supported.
 
+This can happen for a variety reasons, for example:
+
+- Some backends do not support certain operations; such as passing a blockTag
+  to an [[EtherscanProvider]] for [call](Provider-call)
+- A [[Contract]] object connected to [[Provider]] (instead of a [[Signer]]) cannot
+  [sign](Signer-signTransaction) or [send](Signer-sendTransaction) transactions
+- a [[Contract]] connected to a [[Signer]] without a [[Provider]] is write-only
+  and cannot estimate gas or execute static calls
 
-_heading: Safety Error Codes
 
-_property: Logger.errors.BUFFER_OVERRUN
+_heading: Safety Error Codes @<errors-safety>
+
+_property: Logger.errors.BUFFER_OVERRUN @<errors--buffer-overrun>
 The amount of data needed is more than the amount of data required,
 which would cause the data buffer to read past its end.
 
-_property: Logger.errors.NUMERIC_FAULT @<errors-NumericFault>
+This can occur if a contract erroneously returns invalid ABI-encoded
+data or RLP data is malformed.
+
+_property: Logger.errors.NUMERIC_FAULT @<errors--numeric-fault>
 There was an invalid operation done on numeric values.
 
 Common cases of this occur when there is [[link-wiki-overflow]],
 [[link-wiki-underflow]] in fixed numeric types or division by zero.
 
 
-_heading: Usage Error Codes
+_heading: Usage Error Codes @<errors-usage>
 
-_property: Logger.errors.INVALID_ARGUMENT @<errors-InvalidArgument>
+_property: Logger.errors.INVALID_ARGUMENT @<errors--invalid-argument>
 The type or value of an argument is invalid. This will generally also
 include the ``name`` and ``value`` of the argument. Any function which
 accepts sensitive data (such as a private key) will include the string
-``[\[REDACTED]\]`` instead of the value passed in.
+``"[\[REDACTED]\]"`` instead of the value passed in.
 
-_property: Logger.errors.MISSING_ARGUMENT @<errors-MissingArgument>
+_property: Logger.errors.MISSING_ARGUMENT @<errors--missing-argument>
 An expected parameter was not specified.
 
-_property: Logger.errors.MISSING_NEW @<errors-MissingNew>
-An object is a Class, but is now being called with ``new``.
+_property: Logger.errors.MISSING_NEW @<errors--missing-new>
+An object is a Class, but is not being called with ``new``.
 
-_property: Logger.errors.UNEXPECTED_ARGUMENT @<errors-UnexpectedArgument>
+_property: Logger.errors.UNEXPECTED_ARGUMENT @<errors--unexpected-argument>
 Too many parameters we passed into a function.
 
 
-_heading: Ethereum Error Codes
+_heading: Ethereum Error Codes @<errors-ethereum>
 
-_property: Logger.errors.CALL_EXCEPTION
+_property: Logger.errors.CALL_EXCEPTION @<errors--call-exception>
 An attempt to call a blockchain contract (getter) resulted in a
-revert or other error.
+revert or other error, such as insufficient gas (out-of-gas) or an
+invalid opcode. This can also occur during gas estimation or if
+waiting for a [[providers-TransactionReceipt]] which failed during execution.
+
+Consult the contract to determine the cause, such as a failed condition
+in a ``require`` statement. The ``reason`` property may provide more
+context for the cause of this error.
 
-_property: Logger.errors.INSUFFICIENT_FUNDS
+_property: Logger.errors.INSUFFICIENT_FUNDS @<errors--insufficient-funds>
 The account is attempting to make a transaction which costs more than is
 available.
 
 A sending account must have enough ether to pay for the value, the gas limit
 (at the gas price) as well as the intrinsic cost of data. The intrinsic cost
-of data is 4 gas for each zero byte and 68 gas for each non-zero byte.
+of data is 4 gas for each zero byte and 68 gas for each non-zero byte, as well
+as 35000 gas if a transaction contains no ``to`` property and is therefore
+expected to create a new account.
 
-_property: Logger.errors.NETWORK_ERROR
+_property: Logger.errors.NETWORK_ERROR @<errors--network>
 An Ethereum network validation error, such as an invalid chain ID.
 
-_property: Logger.errors.NONCE_EXPIRED
+_property: Logger.errors.NONCE_EXPIRED @<errors--nonce-expired>
 The nonce being specified has already been used in a mined transaction.
 
-_property: Logger.errors.REPLACEMENT_UNDERPRICED
+_property: Logger.errors.REPLACEMENT_UNDERPRICED @<errors--replacement-underpriced>
 When replacing a transaction, by using a nonce which has already been sent to
 the network, but which has not been mined yet the new transaction must specify
 a higher gas price.
 
 This error occurs when the gas price is insufficient to //bribe// the transaction
 pool to prefer the new transaction over the old one. Generally, the new gas price
 should be about 50% + 1 wei more, so if a gas price of 10 gwei was used, the
-replacement should be 15.000000001 gwei.
+replacement should be 15.000000001 gwei. This is not enforced by the protocol, as
+it deals with unmined transactions, and can be configured by each node, however
+to ensure a transaction is propagated to a miner it is best practice to follow
+the defaults most nodes have enabled.
 
-_property: Logger.errors.UNPREDICTABLE_GAS_LIMIT
+_property: Logger.errors.UNPREDICTABLE_GAS_LIMIT @<errors--unpredicatable-gas-limit>
 When estimating the required amount of gas for a transaction, a node is queried for
 its best guess.
 
