or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-web3-eth-iban

Converts Ethereum addresses to IBAN addresses and vice versa using ISO13616 standard

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/web3-eth-iban@4.0.x

To install, run

npx @tessl/cli install tessl/npm-web3-eth-iban@4.0.0

index.mddocs/

web3-eth-iban

Web3-eth-iban provides utilities for converting between Ethereum addresses and International Bank Account Number (IBAN) format addresses. It implements the ISO13616 standard for IBAN validation and conversion, enabling interoperability between blockchain and traditional banking systems.

Package Information

  • Package Name: web3-eth-iban
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install web3-eth-iban

Core Imports

import { Iban } from "web3-eth-iban";

For CommonJS:

const { Iban } = require("web3-eth-iban");

Default import (also available):

import Iban from "web3-eth-iban";

Basic Usage

import { Iban } from "web3-eth-iban";

// Create IBAN from Ethereum address
const iban = Iban.fromAddress("0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8");
console.log(iban.toString()); // "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"

// Convert IBAN back to Ethereum address
const address = iban.toAddress();
console.log(address); // "0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8"

// Validate IBAN
const isValid = Iban.isValid("XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS");
console.log(isValid); // true

// Create indirect IBAN
const indirectIban = Iban.createIndirect({
  institution: "XREG",
  identifier: "GAVOFYORK"
});
console.log(indirectIban.toString()); // "XE81ETHXREGGAVOFYORK"

Architecture

Web3-eth-iban implements two types of IBAN formats:

  • Direct IBAN: Full Ethereum address encoded as IBAN (34-35 characters) - convertible to/from Ethereum addresses
  • Indirect IBAN: Institution-based IBAN format (20 characters) - used for routing and identification, not directly convertible to addresses

The library provides both static utility methods for one-off operations and instance methods for working with specific IBAN objects.

Capabilities

IBAN Creation

Create IBAN instances from various inputs including Ethereum addresses, BBAN strings, and institutional components.

/**
 * Construct a direct or indirect IBAN that has conversion methods and validity checks
 * @param iban - a Direct or an Indirect IBAN string
 */
constructor(iban: string): Iban;

/**
 * Create IBAN from Ethereum address
 * @param address - an Ethereum address
 * @returns Iban instance
 */
static fromAddress(address: HexString): Iban;

/**
 * Create IBAN from Basic Bank Account Number
 * @param bban - the BBAN to convert to IBAN
 * @returns Iban instance
 */
static fromBban(bban: string): Iban;

/**
 * Create indirect IBAN from institution and identifier
 * @param options - object with institution and identifier
 * @returns Iban instance
 */
static createIndirect(options: IbanOptions): Iban;

IBAN Validation

Validate IBAN format and checksums according to ISO13616 standard.

/**
 * Check if a string is a valid IBAN
 * @param iban - string to validate
 * @returns true if valid IBAN
 */
static isValid(iban: string): boolean;

/**
 * Check if the early provided IBAN is correct
 * @returns true if valid IBAN
 */
isValid(): boolean;

/**
 * Check if IBAN is Direct (length 34 or 35)
 * @param iban - IBAN to check
 * @returns true if Direct IBAN
 */
static isDirect(iban: string): boolean;

/**
 * Check if this IBAN is Direct
 * @returns true if Direct IBAN
 */
isDirect(): boolean;

/**
 * Check if IBAN is Indirect (length 20)
 * @param iban - IBAN to check
 * @returns true if Indirect IBAN
 */
static isIndirect(iban: string): boolean;

/**
 * Check if this IBAN is Indirect
 * @returns true if Indirect IBAN
 */
isIndirect(): boolean;

Address Conversion

Convert between Ethereum addresses and direct IBAN format.

/**
 * Convert direct IBAN to Ethereum address
 * @param iban - a Direct IBAN address
 * @returns equivalent Ethereum address
 */
static toAddress(iban: string): HexString;

/**
 * Convert this direct IBAN to Ethereum address
 * @returns equivalent Ethereum address
 */
toAddress(): HexString;

/**
 * Convert Ethereum address to IBAN string
 * @param address - an Ethereum address
 * @returns equivalent IBAN string
 */
static toIban(address: HexString): string;

IBAN Information Extraction

Extract components and metadata from IBAN strings.

/**
 * Get client identifier from indirect IBAN
 * @returns client identifier or empty string for direct IBANs
 */
client(): string;

/**
 * Get IBAN checksum (positions 2-4)
 * @returns checksum string
 */
checksum(): string;

/**
 * Get institution identifier from indirect IBAN
 * @returns institution identifier or empty string for direct IBANs
 */
institution(): string;

/**
 * Get the IBAN string
 * @returns IBAN string
 */
toString(): string;

Types

/**
 * Configuration object for creating indirect IBANs
 */
interface IbanOptions {
  /** Institution identifier */
  institution: string;
  /** Client identifier */
  identifier: string;
}

/**
 * Hexadecimal string type (imported from web3-types package)
 */
type HexString = import('web3-types').HexString;

Error Handling

The library throws the following errors:

  • Error("Invalid IBAN was provided") - When constructor receives invalid IBAN format
  • InvalidAddressError(address) - When provided address is not a valid Ethereum address
  • Error("Iban is indirect and cannot be converted. Must be length of 34 or 35") - When attempting to convert indirect IBAN to address

Usage Examples:

import { Iban } from "web3-eth-iban";

// Handle invalid IBAN
try {
  const iban = new Iban("INVALID");
} catch (error) {
  console.log(error.message); // "Invalid IBAN was provided"
}

// Handle invalid address
try {
  const iban = Iban.fromAddress("0x123"); // Invalid address
} catch (error) {
  console.log(error.constructor.name); // "InvalidAddressError"
}

// Handle indirect IBAN conversion
try {
  const iban = new Iban("XE81ETHXREGGAVOFYORK"); // Indirect IBAN
  const address = iban.toAddress(); // Will throw
} catch (error) {
  console.log(error.message); // "Iban is indirect and cannot be converted..."
}