日志

这有一些简便的logging(日志)工具,用于简化和标准化Ethers库中的error facilities。

Logger库没有依赖关系,并且非常轻量级,因此可以很容易地包含在每个库中。

审查(Censorship)功能依赖于包含的ether库的一个实例。在大型绑定包中或使用npm link时,可能使用的方式就有所不同。 如果需要使用此功能,请确保你绑定的配置是正确的。

Logger

new ethers.utils.Logger( version )

创建一个新的logger包含所有错误抛出的版本(version)。

Logger.globalLogger( ) Logger

返回单例全局的logger。

Logging Output

logger.debug( ...args ) void

打印 debugging 信息。

logger.info( ...args ) void

打印通用的信息。

logger.warn( ...args ) void

打印 warnings 信息。

Errors

这些函数支持当前的审查(Censorship),还可以帮助创建一个用于检测和处理Ethers中的错误的标准错误模型。

logger.makeError( message [ , code = UNKNOWN_ERROR [ , params ] ] ) Error

创建一个带有消息(message)、可选代码(code)和附加参数集(params)的Error对象。用于需要拒绝错误而不是抛出错误时。

logger.throwError( message [ , code = UNKNOWN_ERROR [ , params ] ] ) never

抛出一个带有消息(message)、可选代码(code)和附加参数集(params)的错误(Error)。

logger.throwArgumentError( message , name , value ) never

抛出一个带有名称(name )和值(value)的INVALID_ARGUMENT错误。

Usage Validation

可以用来确保各种属性(properties)和行为(actions)是安全的。

logger.checkAbstract( target , kind ) void

如果targetkind,则抛出UNSUPPORTED_OPERATION错误, 否则执行与checkNew相同的操作。

这可以用来确保抽象类没有被实例化。

logger.checkArgumentCount( count , expectedCount [ , message ) void

如果count不等于expectedCount,则抛出MISSING_ARGUMENTUNEXPECTED_ARGUMENT错误。

logger.checkNew( target , kind ) void

如果target不是有效的thistarget值,则抛出MISSING_NEW错误。 这有助于确保类的调用者是使用new关键字的。

logger.checkNormalize( message ) void

检查运行环境(environment)是否具有正常运行String.normalize的功能。 如果没有,则抛出UNSUPPORTED_OPERATION错误。

logger.checkSafeUint53( value [ , message ] ) void

如果value作为JavaScript number是不安全的,则抛出NUMERIC_FAULT错误。

Censorship

Logger.setCensorship( censor [ , permanent = false ] ) void

设置错误审查(error censorship),可选地设置哪些错误可以被审查。

在生产应用程序中,这可以通过屏蔽错误的消息(message)和值(values)来防止错误泄露信息。

这可能会影响调试,使调试变得更加困难。

Logger.setLogLevel( logLevel ) void

设置日志级别,使日志输出低于特定的日志级别

Errors

Ethers中的每个错误都有一个代码(code)值,它是一个字符串,将匹配以下错误代码之一。

通用的错误代码

Logger.errors.NOT_IMPLEMENTED

该操作还没有实现。一般发生在:调用尚未完全实现其抽象超类的子类的方法时。

Logger.errors.SERVER_ERROR

与服务器通信时发生错误。

出现这种情况的原因有很多,例如:

  • CORS的问题;大多数都是这种问题,属于最难诊断和修复的,所以熟悉CORS对你是很有帮助的; 一些后端允许你配置你的CORS,例如geth命令行或配置文件,或者是INFURA和Alchemy的通过指定Origins或者methods配置的dashboards等。
  • SSL的问题;例如,如果你试图通过HTTP连接到本地节点,但节点提供的是HTTPS网站的内容。
  • 链接的问题;防火墙正在阻止进入服务器的流量。
  • 服务器的问题;服务器已关闭,或返回500的错误码。
  • 后端DDoS mitigation proxy问题;例如,Etherscan在Cloudflare代理后运行,如果请求是通过特定的用户代理发送的,或者在某些情况下,客户端fingerprint被检测为机器人,Cloudflare代理将阻塞流量

Logger.errors.TIMEOUT

发生超时错误。

Logger.errors.UNKNOWN_ERROR

一个通用的未知错误。

Logger.errors.UNSUPPORTED_OPERATION

不支持该操作。

这种情况可能有多种原因,例如:

Safety Error Codes

Logger.errors.BUFFER_OVERRUN

所需的数据量大于规定的数据量,这将导致数据缓冲区读取超过其末端。

如果合约错误地返回无效的abi编码数据或RLP数据格式不正确,就会发生这种情况。

Logger.errors.NUMERIC_FAULT

对数值进行了无效的操作。

这种情况通常发生在overflow、固定数值类型中的arithmetic underflow、或除零时。

Usage Error Codes

Logger.errors.INVALID_ARGUMENT

参数的类型或值无效。这通常还包括参数的namevalue。 任何接受敏感数据(如私钥)的函数将包含string"[[REDACTED]]"而不是传入的值。

Logger.errors.MISSING_ARGUMENT

未指定预期参数。

Logger.errors.MISSING_NEW

对象是一个类,但没有通过new调用。

Logger.errors.UNEXPECTED_ARGUMENT

传递给函数的参数过多。

Ethereum Error Codes

Logger.errors.CALL_EXCEPTION

尝试调用区块链合约(getter)会导致revert或其他错误,例如gas不足(out-of-gas)或无效的操作码。 这也可能发生在gas估计或等待TransactionReceipt执行过程中失败。

通过合约来确定原因,例如require语句中的失败条件。reason属性可以为此错误的原因提供更多上下文。

Logger.errors.INSUFFICIENT_FUNDS

该帐户正试图进行一个费用超过自身可用余额的交易。

发送帐户必须有足够的以太币来对value、gas limit、以及数据的内在成本进行支付。 数据的内在成本是每个零字节4个gas,每个非零字节68个gas,如果交易不包含to属性,表示要部署一个新合约,则为35000个gas。

Logger.errors.NETWORK_ERROR

以太坊网络验证错误,例如无效的链ID。

Logger.errors.NONCE_EXPIRED

指定的nonce已经被挖出的区块中的交易所使用。

Logger.errors.REPLACEMENT_UNDERPRICED

当替换一个交易(已经发送到网络但尚未被挖出)时,通过相同nonce,新的交易必须比指定替换的的gas price更高。

当天然气价格不足以贿赂(bribe)交易池(期望使其选择新的交易而不是旧的交易时)就会发生这种错误。 一般情况下,新的gas price应该是比原来多50% + 1 wei,即如果使用10 gwei的gas price, 更换的应该是15.000000001gwei。协议没有强制执行这一点,因为它处理未被挖出的交易可以由每个节点自由配置, 但是要确保将交易传播到一个矿工手里,最好是遵循大多数节点启用的默认值。

Logger.errors.TRANSACTION_REPLACED

当一个交易被用户替换时,即广播的新交易替换了节点内存池中相同正在等待被打包的相同nonce的旧交易,就会发生此错误,因为 正在等待被打包的旧交易已经失效了。

这种情况可能有多种原因,但最常见的原因是用户提高了gas price(这改变了交易哈希)去"加速"交易, 或者用户在其客户端"取消"了交易。在任何一种情况下,这通常是通过以更高的gas price去贿赂矿工来实现的。

此错误将具有附加属性:cancelled, hash, reason, receiptreplacement

有关更多详细信息,请参阅wait方法的TransactionResponse

Logger.errors.UNPREDICTABLE_GAS_LIMIT

在估计一个交易所需的gas数量时,查询一个节点以获得其最佳的预测值。

如果节点不能(或不愿意)预测成本值,则会发生此错误。

对于这种情况,最好的解决办法是在交易中手动指定一个gas limit。

该错误还会表明,如果一个没有token的帐户试图发送token,交易无论如何都将失败。

Log Levels

Logger.levels.DEBUG

记录所有输出信息,包括调试信息。

Logger.levels.INFO

仅记录信息、警告和错误的输出。

Logger.levels.WARNING

仅记录警告和错误的输出。

Logger.levels.ERROR

仅记录错误的输出。

Logger.levels.OFF

不输出日志。