From f0a88f551f5cccd586a6eca9731f212562dc3ba2 Mon Sep 17 00:00:00 2001 From: Richard Moore Date: Thu, 4 Feb 2021 18:59:51 -0500 Subject: [PATCH] docs: better linking to errors in docs --- docs.wrm/api/utils/address.wrm | 4 +- docs.wrm/api/utils/logger.wrm | 129 +++++++++++++++++++++------------ 2 files changed, 86 insertions(+), 47 deletions(-) diff --git a/docs.wrm/api/utils/address.wrm b/docs.wrm/api/utils/address.wrm index e7951ba73..c5e5839f6 100644 --- 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]]> @ string<[IcapAddress](address-icap)> @ @SRC
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 @ @SRC
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 index e61274a1b..36797cf03 100644 --- a/docs.wrm/api/utils/logger.wrm +++ b/docs.wrm/api/utils/logger.wrm @@ -48,39 +48,38 @@ Throw an Error with //message// and an optional //code// and additional //params// set. _property: logger.throwArgumentError(message, name, value) => never @SRC -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 -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 @ @SRC +If //target// is //kind//, throws a [UNSUPPORTED_OPERATION](errors--unsupported-operation) error +otherwise performs the same operations as [checkNew](Logger-checkNew). -_property: logger.checkArgumentCount(count, expectedCount [ , message) => void @SRC -If //count// is not equal to //expectedCount//, throws a [MISSING_ARGUMENT](errors-MissingArgument) -or [UNEXPECTED_ARGUMENT](errors-UnexpectedArgument) error. +This is useful for ensuring abstract classes are not being instantiated. -_property: logger.checkNew(target, kind) => void @SRC +_property: logger.checkArgumentCount(count, expectedCount [ , message) => void @ @SRC +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 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 +_property: logger.checkNormalize(message) => void @ @SRC 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 +_property: logger.checkSafeUint53(value [, message ]) => void @ @SRC 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 @ -_property: Logger.setCensorship(censor [ , permanent = false ]) => void @SRC +_property: Logger.setCensorship(censor [ , permanent = false ]) => void @ @SRC Set error censorship, optionally preventing errors from being uncensored. In production applications, this prevents any error from leaking information @@ -88,7 +87,7 @@ by masking the message and values of errors. This can impact debugging, making it substantially more difficult. -_property: Logger.setLogLevel(logLevel) => void @SRC +_property: Logger.setLogLevel(logLevel) => void @ @SRC Set the log level, to suppress logging output below a [particular log level](Logger-levels). @@ -98,76 +97,113 @@ 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 @ -_property: Logger.errors.NOT_IMPLEMENTED -The operation is not implemented. +_property: Logger.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 @ There was an error communicating with a server. -_property: Logger.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 @ A timeout occurred. -_property: Logger.errors.UNKNOWN_ERROR @ +_property: Logger.errors.UNKNOWN_ERROR @ A generic unknown error. -_property: Logger.errors.UNSUPPORTED_OPERATION @ +_property: Logger.errors.UNSUPPORTED_OPERATION @ The operation is not supported. +This can happen for a variety reasons, for example: -_heading: Safety Error Codes +- 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 -_property: Logger.errors.BUFFER_OVERRUN + +_heading: Safety Error Codes @ + +_property: Logger.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 @ +This can occur if a contract erroneously returns invalid ABI-encoded +data or RLP data is malformed. + +_property: Logger.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 @ -_property: Logger.errors.INVALID_ARGUMENT @ +_property: Logger.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 @ +_property: Logger.errors.MISSING_ARGUMENT @ An expected parameter was not specified. -_property: Logger.errors.MISSING_NEW @ -An object is a Class, but is now being called with ``new``. +_property: Logger.errors.MISSING_NEW @ +An object is a Class, but is not being called with ``new``. -_property: Logger.errors.UNEXPECTED_ARGUMENT @ +_property: Logger.errors.UNEXPECTED_ARGUMENT @ Too many parameters we passed into a function. -_heading: Ethereum Error Codes +_heading: Ethereum Error Codes @ -_property: Logger.errors.CALL_EXCEPTION +_property: Logger.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. -_property: Logger.errors.INSUFFICIENT_FUNDS +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 @ 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 @ An Ethereum network validation error, such as an invalid chain ID. -_property: Logger.errors.NONCE_EXPIRED +_property: Logger.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 @ 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. @@ -175,9 +211,12 @@ 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 @ When estimating the required amount of gas for a transaction, a node is queried for its best guess.