区块链Web3【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址https://gitcode.com/gh_mirrors/we/web3.js点击查看免费下载本篇指南聚焦 web3.js 从 1.x 升级到 4.x 时web3.eth.ibanIBAN 与以太坊地址互转工具的全部破坏性变更。你将掌握新版 Iban 类的构造校验规则、toAddress/fromAddress在新旧版本中的行为差异与错误消息格式变化并通过仓库源码与单元测试获得可直接落地的迁移与编码依据。背景web3.js 中的 IBAN 是什么IBANInternational Bank Account Number国际银行账号是一套 ISO 13616 标准下的银行账号编码体系。web3.js 借助它提供了一套以太坊地址与 IBAN/BBAN 之间的双向转换能力既可以把一个以太坊地址编码为 IBAN 字符串常用于将地址嵌入支付场景或与银行系统对接也可以把合法的 Direct IBAN 解码回以太坊地址。在 4.x 中该能力由独立包web3-eth-iban提供核心实现位于 packages/web3-eth-iban/src/iban.ts。IBAN 在 web3.js 语境下分为两类Direct IBAN直接 IBAN长度为 34 或 35 的字符串其主体是某个以太坊地址的 base36 编码可逆转换回地址。例如XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS。Indirect IBAN间接 IBAN长度为 20 的字符串用于表示「机构institution 客户标识identifier」例如XE81ETHXREGGAVOFYORK其中ETH之后依次携带机构码与客户码。对应的类型定义IbanOptions位于 packages/web3-eth-iban/src/types.tsexport type IbanOptions { institution: string; identifier: string; };破坏性变更一Iban 构造函数开始强制校验输入1.x 的行为在 1.x 中new Iban(str)会无条件接受传入的字符串不做任何长度或格式校验。这意味着把任意字符串包括明显非 IBAN 的文本传入构造函数都不会报错错误往往被推迟到后续调用时才暴露排查成本较高。4.x 的行为4.x 的构造函数在实例化时即进行长度校验源码见 packages/web3-eth-iban/src/iban.ts#L222-L228public constructor(iban: string) { if (Iban.isIndirect(iban) || Iban.isDirect(iban)) { this._iban iban; } else { throw new Error(Invalid IBAN was provided); } }只有当字符串长度为间接 IBAN 的 20或直接 IBAN 的 34/35时才会被接受否则立即抛出Error错误消息为Invalid IBAN was provided。对应的长度判定逻辑同样在源码中packages/web3-eth-iban/src/iban.ts#L109-L111isDirect判断长度为 34 或 35packages/web3-eth-iban/src/iban.ts#L144-L146isIndirect判断长度为 20。两者均同时提供静态方法Iban.isDirect(str)/Iban.isIndirect(str)与实例方法iban.isDirect()/iban.isIndirect()实例方法内部委托给静态实现例如isDirect实例方法即return Iban.isDirect(this._iban);见 packages/web3-eth-iban/src/iban.ts#L127-L129。// 1.x以下代码不报错问题延迟暴露 const bad new Iban(随便一段文本); // 4.x直接抛出 Error: Invalid IBAN was provided try { const bad new Iban(随便一段文本); } catch (error) { console.log(error.message); // Invalid IBAN was provided } // 4.x合法输入正常工作 const direct new Iban(XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS); // 长度 34合法 const indirect new Iban(XE81ETHXREGGAVOFYORK); // 长度 20合法迁移要点升级后请确保传入构造函数的字符串严格满足 20 或 34/35 的长度要求建议在构造前先用Iban.isValid()或isDirect/isIndirect做前置校验以区分「长度合法但内容非法」与「长度本身非法」两种场景。破坏性变更二对非 Direct IBAN 调用toAddress行为统一1.x 的行为1.x 中toAddress的行为取决于调用方式且仅在传入的 IBAN 不是 Direct 类型时表现出不一致实例方法new Iban(address).toAddress()返回空字符串静默失败静态方法Iban.toAddress(address)抛出错误消息为IBAN is indirect and can\t be converted。同样的输入、两种 API、两种结果极易导致上游代码拿到空字符串后产生难以定位的后续错误。4.x 的行为4.x 统一了两者只要提供的 IBAN 不是 Direct即长度不是 34 或 35无论调用静态方法还是实例方法都会抛出错误消息统一为Iban is indirect and cannot be converted. Must be length of 34 or 35实例方法实现见 packages/web3-eth-iban/src/iban.ts#L330-L339public toAddress (): HexString { if (this.isDirect()) { // check if Iban can be converted to an address const base36 this._iban.slice(4); const parsedBigInt Iban._parseInt(base36, 36); // convert the base36 string to a bigint const paddedBigInt leftPad(parsedBigInt, 40); return toChecksumAddress(paddedBigInt); } throw new Error(Iban is indirect and cannot be converted. Must be length of 34 or 35); };而静态方法只是对实例方法的委托见 packages/web3-eth-iban/src/iban.ts#L310-L313public static toAddress (iban: string): HexString { const ibanObject new Iban(iban); return ibanObject.toAddress(); };这也解释了为什么静态与实例行为能够保持一致它们走的是同一条代码路径。该行为在单元测试中有明确覆盖见 packages/web3-eth-iban/test/unit/iban.test.ts#L42-L68其非法用例数据定义在 packages/web3-eth-iban/test/fixtures/iban.ts#L27-L32export const invalidIbanToAddressData: [string, Error][] [ [ XE81ETHXREGGAVOFYORK, new Error(Iban is indirect and cannot be converted. Must be length of 34 or 35), ], ];迁移要点升级后不要再依赖「实例方法返回空字符串」这一旧行为对可能为 Indirect 的 IBAN 调用toAddress前应先用iban.isDirect()判断或者用try/catch捕获统一抛出的Error。// 1.x实例方法静默返回 静态方法抛错 // 4.x两种调用方式都抛错行为一致 const iban new Iban(XE81ETHXREGGAVOFYORK); try { iban.toAddress(); } catch (error) { console.log(error.message); // Iban is indirect and cannot be converted. Must be length of 34 or 35 }破坏性变更三fromAddress对非法地址抛出结构化错误对象1.x 的行为1.x 中当传入的字符串不是合法以太坊地址时fromAddress抛出普通Error消息格式为拼接字符串Provided address is not a valid address: address4.x 的行为4.x 改为抛出 web3.js 统一错误体系中的InvalidAddressError错误对象其消息与错误码如下错误码1005常量ERR_INVALID_ADDRESS消息模板Invalid value given ${address}. Error: invalid ethereum address该错误对象携带结构化信息code、name等便于按错误码做程序化处理而不是依赖字符串匹配。其实现链路完全可以在仓库中追踪fromAddress先通过web3-validator的isAddress校验不合法则抛出InvalidAddressError见 packages/web3-eth-iban/src/iban.ts#L284-L293public static fromAddress(address: HexString): Iban { if (!isAddress(address)) { throw new InvalidAddressError(address); } const num BigInt(hexToNumber(address)); const base36 num.toString(36); const padded leftPad(base36, 15); return Iban.fromBban(padded.toUpperCase()); }错误码常量定义于 packages/web3-errors/src/error_codes.ts#L148export const ERR_INVALID_ADDRESS 1005;InvalidAddressError继承自InvalidValueError并固定code ERR_INVALID_ADDRESS、错误子消息为invalid ethereum address见 packages/web3-errors/src/errors/utils_errors.ts#L55-L61。最终消息由InvalidValueError统一拼接模板为Invalid value given ${value}. Error: ${msg}.见 packages/web3-errors/src/web3_error_base.ts#L111-L119。因此 4.x 下实际抛出的完整错误消息为Invalid value given 0x1. Error: invalid ethereum address.含结尾句号并可通过error.code 1005精确识别。// 1.x消息为 Provided address is not a valid address: 0x1 // 4.x结构化错误对象code 1005 try { Iban.fromAddress(0x1); // 非法地址 } catch (error: any) { console.log(error.code); // 1005 console.log(error.message); // Invalid value given 0x1. Error: invalid ethereum address. }迁移要点如果旧代码曾用字符串includes(not a valid address)判断错误升级后必须改为检查error.code 1005或error instanceof InvalidAddressError后者可从web3-errors包导入。另外注意isAddress对地址格式的校验更严格——测试数据 packages/web3-eth-iban/test/fixtures/iban.ts#L34-L38 显示不仅0x1这类过短输入会被拒绝checksum 不合法的地址如0xE247a45c287191d435A8a5D72A7C8dc030451E9F和-0x...前缀输入同样会被判为非法。迁移后的 Iban API 全览4.x安装方式Iban 功能随web3主包一起提供也可单独安装web3-eth-iban使用用法说明见 packages/web3-eth-iban/src/iban.ts 头部注释# 方式一使用完整 web3 包 npm i web3 # 或 yarn add web3 # 方式二仅使用独立包 npm i web3-eth-iban # 或 yarn add web3-eth-iban// 方式一 import { Web3 } from web3; const web3 new Web3(https://mainnet.infura.io/v3/YOURPROJID); const iban new web3.eth.Iban(XE81ETHXREGGAVOFYORK); console.log(iban.checksum()); // 81 // 方式二 import { Iban } from web3-eth-iban; const iban2 new Iban(XE81ETHXREGGAVOFYORK); console.log(iban2.checksum()); // 81web3-eth-iban的入口 packages/web3-eth-iban/src/index.ts 同时导出了Iban类、其全部成员及IbanOptions类型并提供了默认导出。转换类 API方法类型说明示例fromAddress(address)静态以太坊地址 → Iban 实例Iban.fromAddress(0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8)toAddress(iban)/iban.toAddress()静态 / 实例Direct IBAN → 以太坊地址Iban.toAddress(XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS)→0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8toIban(address)静态以太坊地址 → IBAN 字符串Iban.toIban(0x00c5...6D8)→XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZSfromBban(bban)静态BBAN → Iban 实例自动计算校验位Iban.fromBban(ETHXREGGAVOFYORK)createIndirect({institution, identifier})静态机构 客户标识 → 间接 Iban 实例Iban.createIndirect({institution: XREG, identifier: GAVOFYORK})其中fromAddress的实现路径是地址 → 十进制 BigInt → base36 字符串 → 左侧补零至 15 位 → 交给fromBban生成带校验位的 IBANtoAddress则是反向去掉XE前缀与校验位后把 base36 的 BBAN 主体解析为 BigInt再补零到 40 位十六进制并用toChecksumAddress还原出带大小写校验和的地址。createIndirect内部实际是Iban.fromBban(ETH institution identifier)见 packages/web3-eth-iban/src/iban.ts#L268-L270。校验类 API方法类型说明isValid(iban)/iban.isValid()静态 / 实例校验字符串是否符合 IBAN 格式且校验位通过 MOD 97/10 计算isDirect(iban)/iban.isDirect()静态 / 实例长度是否为 34 或 35isIndirect(iban)/iban.isIndirect()静态 / 实例长度是否为 20isValid的静态实现见 packages/web3-eth-iban/src/iban.ts#L182-L187同时做了两件事正则约束格式^XE[0-9]{2}(ETH[0-9A-Z]{13}|[0-9A-Z]{30,31})$要求以XE开头、第 3-4 位为两位校验数字其后是ETH开头的 13 位间接主体或 30-31 位直接主体并要求_mod9710(_iso13616Prepare(iban)) 1。也就是说只有格式与校验位同时正确才返回trueIban.isValid(XE81ETHXREGGAVOFYORK); // true Iban.isValid(XE82ETHXREGGAVOFYORK); // false校验位不正确ISO 13616 的_iso13616Prepare将 IBAN 前 4 位移到末尾并把字母映射为数字A10, B11, …, Z35随后按 ISO 7064 的 MOD 97/10 算法计算余数这两段私有静态工具位于 packages/web3-eth-iban/src/iban.ts#L52-L94。fromBban生成校验位时也是先以00占位计算余数再取98 - remainder的末两位作为真实校验位见 packages/web3-eth-iban/src/iban.ts#L244-L251。访问器类 API方法说明示例输入XE81ETHXREGGAVOFYORKiban.client()返回间接 IBAN 的客户标识从第 11 位起非间接返回GAVOFYORKiban.institution()返回机构码第 7-11 位非间接返回XREGiban.checksum()返回第 3-4 位校验数字81iban.toString()返回原始 IBAN 字符串XE81ETHXREGGAVOFYORK以上访问器的实现分别位于 packages/web3-eth-iban/src/iban.ts#L369-L371、#L398-L400、#L384-L386、#L412-L414。测试数据中的合法/非法样本仓库在 packages/web3-eth-iban/test/fixtures/iban.ts 中提供了可直接复用的样本可用于自测或编写迁移测试// 合法 Direct IBAN → 地址 双向样本 [XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36, 0x8ba1f109551bD432803012645Ac136ddd64DBA72] [XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS, 0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8] // 合法间接 IBANcreateIndirect 输入 → 输出 { institution: XREG, identifier: GAVOFYORK } → XE81ETHXREGGAVOFYORK { institution: XREG, identifier: HELLOWORL } → XE48ETHXREGHELLOWORL // isValid 反例静态校验 ZZ68539007547034 // 不以 XE 开头 BE68539007547034 // 非以太坊 IBAN 国家码 LC55HEMM000100010012001200023015这些样本在 packages/web3-eth-iban/test/unit/iban.test.ts 中被it.each参数化地用于覆盖构造函数、toAddress静态与实例、toIban、fromAddress、fromBban、createIndirect、isValid静态与实例、isDirect、isIndirect、client、institution、checksum等全部公开方法。迁移检查清单完成web3.eth.iban从 1.x 到 4.x 的升级后建议对照以下清单自查构造输入所有new Iban(str)的入参是否保证长度为 20、34 或 35非法长度会立即抛出Invalid IBAN was provided。toAddress调用是否存在对间接 IBAN 调用toAddress的旧逻辑曾依赖返回现在静态与实例方法都会抛出Iban is indirect and cannot be converted. Must be length of 34 or 35请改用isDirect()前置判断或捕获异常。fromAddress错误处理是否仍用字符串匹配not a valid address4.x 中应检查error.code 1005ERR_INVALID_ADDRESS或从web3-errors导入InvalidAddressError做instanceof判断同时注意严格地址校验会拒绝 checksum 错误的地址。错误码风格4.x 统一采用带code字段的结构化错误对象建议在全局错误处理中按code分类而非按消息文本匹配。web3.eth.iban的迁移只是整个 1.x → 4.x 升级的一部分。更多迁移主题web3.eth.subscribe、合约、账户、ENS、工具函数等可参见 15_web3_upgrade_guide 目录其中订阅相关迁移见 subscribe_migration_guide。若在迁移中需要同时理解 4.x 默认返回类型等全局行为变化可一并参考 09_web3_config 指南。赞分享区块链Web3【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址https://gitcode.com/gh_mirrors/we/web3.js点击查看免费下载相关推荐5分钟快速上手免费Windows字体自定义终极指南5分钟快速上手免费Windows字体自定义终极指南 还在为Windows系统千篇一律的字体而烦恼吗微软从Windows 8.1开始取消了系统字体自定义功能区块链Web3SQLFluff 跨版本升级迁移指南从 1.x 到 4.x 的破坏性变更与配置迁移全解析SQLFluff 跨版本升级迁移指南从 1.x 到 4.x 的破坏性变更与配置迁移全解析 本篇技术指南以 SQLFluff 官方文档 releasenotes代码质量Lint格式化静态分析开发工具SQLFluff 版本升级迁移指南从 1.x 到 4.x 的破坏性变更与实战应对SQLFluff 版本升级迁移指南从 1.x 到 4.x 的破坏性变更与实战应对 SQLFluff 是一个模块化的 SQL 解析器、Linter 与自动格式化代码质量Lint格式化静态分析开发工具上一篇10分钟上手X-Road开发者必备的本地测试环境搭建指南下一篇SpriteJS 矢量图形绘制Path、Polyline 和几何形状详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
