Base58 Encoding in Blockchain Architecture: Bitcoin, IPFS & Checksum Verification Mechanics

+---------------------------------------------------------------------------------------------------+
|                        RADIX ENCODING PIPELINE & DESIGN TRADEOFFS                                 |
+---------------------------------------------------------------------------------------------------+
|  Raw Cryptographic Binary Payload: [ 256-bit Hash / ECDSA Public Key Hash ]                       |
+---------------------------------------------------------------------------------------------------+
                                                  |
           +--------------------------------------+--------------------------------------+
           |                                                                             |
           v                                                                             v
+---------------------------------------------------+     +-----------------------------------------+
|        BASE64 (RFC 4648) - 64 Characters          |     |           HEXADECIMAL (BASE16)          |
|  * Uses: [A-Z], [a-z], [0-9], '+', '/', '='       |     |  * Uses: [0-9], [a-f]                   |
|  * Flaws: Non-alphanumeric delimiters break URLs; |     |  * Flaws: 64-character bloat;           |
|    double-click line selection fails;             |     |    visually unreadable;                 |
|    severe human typographic collisions (0/O, 1/l) |     |    zero native error detection          |
+---------------------------------------------------+     +-----------------------------------------+
                                                  \                               /
                                                   \                             /
                                                    v                           v
+---------------------------------------------------------------------------------------------------+
|                  SATOSHI NAKAMOTO'S INNOVATION: BASE58 & BASE58CHECK (2009)                       |
|  * 58 Clean Alphanumeric Characters (Strictly Alphanumeric: No +, /, or =)                        |
|  * Deliberate elimination of the 4 visually ambiguous glyphs: '0', 'O', 'I', 'l'                  |
|  * Arbitrary-precision Big-Integer Radix-58 Division Loop (Full byte array encoding)              |
|  * Integrated Double-SHA256 4-Byte Checksum Cascade (Fatal typo detection probability > 99.9999%)  |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        SATOSHI NAKAMOTO BASE58 ALPHABET GLYPH MAP                                 |
+---------------------------------------------------------------------------------------------------+
|  Index:  0  1  2  3  4  5  6  7  8                                                                |
|  Char:   1  2  3  4  5  6  7  8  9     [Digits 1-9; Digit '0' is completely excluded]            |
+---------------------------------------------------------------------------------------------------+
|  Index:  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32                 |
|  Char:   A  B  C  D  E  F  G  H  J  K  L  M  N  P  Q  R  S  T  U  V  W  X  Y  Z                 |
|          ['I' and 'O' are completely excluded]                                                    |
+---------------------------------------------------------------------------------------------------+
|  Index: 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57              |
|  Char:   a  b  c  d  e  f  g  h  i  j  k  m  n  o  p  q  r  s  t  u  v  w  x  y  z              |
|          ['l' is completely excluded]                                                             |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        BASE58 ALPHABET DIALECT COMPARISONS                                        |
+---------------------------------------------------------------------------------------------------+
|  Dialect         Alphabet Character Ordering String                                               |
+---------------------------------------------------------------------------------------------------+
|  Bitcoin         123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz                      |
|  (Standard)      * Digits 1-9 first, followed by uppercase A-Z (minus I,O), then lowercase a-z    |
+---------------------------------------------------------------------------------------------------+
|  Ripple          rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz                      |
|  (XRP Ledger)    * Scrambled alphabet designed so Ripple accounts start with 'r'                  |
+---------------------------------------------------------------------------------------------------+
|  Flickr          123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ                      |
|  (Short URLs)    * Digits first, then lowercase letters, followed by uppercase letters            |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        ARBITRARY-PRECISION BASE-58 DIVISION CONVERTER                             |
+---------------------------------------------------------------------------------------------------+
|  Input Byte Array -> Treated as Single Large Integer X                                            |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  WHILE X > 0 DO:                                                                                  |
|      Remainder  = X mod 58                                                                        |
|      X          = floor(X / 58)                                                                   |
|      OutputChar = Alphabet[Remainder]                                                             |
|      Prepend OutputChar to Encoded String                                                         |
|  ENDWHILE                                                                                         |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  COUNT LEADING ZERO BYTES (0x00) in Original Input Byte Array:                                    |
|  * For every leading 0x00 byte, prepend a literal '1' (Alphabet[0]) to the final string!          |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        BASE58CHECK ENCODING PIPELINE SPECIFICATION                                |
+---------------------------------------------------------------------------------------------------+
|  1. Raw Payload: 20-byte RIPEMD-160 Public Key Hash                                               |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  2. Prepend Version Byte: [ Version Byte (1B) ] + [ Payload (20B) ] -> Total 21 Bytes             |
|     * Bitcoin Mainnet P2PKH: 0x00                                                                 |
|     * Bitcoin Mainnet P2SH:  0x05                                                                 |
|     * Bitcoin Testnet:       0x6F                                                                 |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  3. Double SHA-256 Checksum Generation:                                                           |
|     Hash1 = SHA-256(Version + Payload)                                                            |
|     Hash2 = SHA-256(Hash1)                                                                        |
|     Checksum = Hash2[0..3]  (First 4 bytes / 32 bits of the double-hash digest)                   |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  4. Assemble 25-byte Binary Vector:                                                               |
|     [ Version (1B) ] + [ Payload (20B) ] + [ Checksum (4B) ]                                       |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  5. Execute Big-Integer Base-58 Encoding:                                                         |
|     Result: 33 to 34 Character String beginning with '1' (e.g. 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa)|
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        BITCOIN P2PKH ADDRESS DERIVATION CASCADE                                   |
+---------------------------------------------------------------------------------------------------+
|  Stage 1: 256-bit CSPRNG Private Key                                                              |
|  Hex: 18E14A7B6A307F426A94F8114701E7C8E774E7F9A47E2C2035DB29A206321725                            |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 2: ECDSA Secp256k1 Point Multiplication (P = k * G) -> 33-byte Compressed Public Key       |
|  Hex: 0250863AD64A87AE8A2FE83C1AF1A8403CB53F53E486D8511DAD8A04887E5B2352                          |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 3: SHA-256 Cryptographic Hash -> 32-byte Digest                                            |
|  Hex: 0B791E440CB9E3C147679160E3DD30E9FF5D8E174725B52D45021A3091551065                            |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 4: RIPEMD-160 Hash (HASH160) -> 20-byte Public Key Hash                                    |
|  Hex: 010966776006953D5567439E5E39F86A0D273BEE                                                   |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 5: Prepend Mainnet Version Byte (0x00) -> 21-byte Extended Hash                            |
|  Hex: 00010966776006953D5567439E5E39F86A0D273BEE                                                 |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 6: Double SHA-256 Checksum Calculation -> First 4 Bytes (0x44BE162A)                       |
|  Hex: 00010966776006953D5567439E5E39F86A0D273BEE44BE162A  (25 bytes total)                       |
+---------------------------------------------------------------------------------------------------+
                                                  |
                                                  v
+---------------------------------------------------------------------------------------------------+
|  Stage 7: Base58 Big-Integer Conversion:                                                          |
|  Final Address: 16UwLL9Risc3QfPqBUvKofHmBQ7wMtjvM                                                 |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        IPFS MULTIHASH BINARY ANATOMY SPECIFICATION                                |
+---------------------------------------------------------------------------------------------------+
|  [ Hash Function Code (varint) ] [ Digest Length in Bytes (varint) ] [ Raw Cryptographic Digest ] |
+---------------------------------------------------------------------------------------------------+
|  * Function Code: 0x12  (Denotes standard SHA-256)                                                |
|  * Digest Length: 0x20  (Denotes 32 bytes / 256 bits)                                             |
|  * Raw Digest:    [ 32 bytes of SHA-256 output ]                                                  |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        DECONSTRUCTING AN IPFS CIDv0 ADDRESS                                       |
+---------------------------------------------------------------------------------------------------+
|  IPFS CIDv0: QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco                                      |
+---------------------------------------------------------------------------------------------------+
|  1. Length: Exactly 46 characters.                                                                |
|  2. Prefix: ALWAYS begins with "Qm" (Why? Because 0x12 0x20 in Base58 encodes to "Qm"!)          |
|  3. Encoding: Pure Base58 (No version byte, No checksum needed because the payload IS the hash!). |
+---------------------------------------------------------------------------------------------------+

+---------------------------------------------------------------------------------------------------+
|                        THE RADIX ENCODING SPECTRUM (EFFICIENCY VS RESILIENCE)                     |
+---------------------------------------------------------------------------------------------------+
|  Base16 (Hex)           Base32 (RFC 4648)         Base58Check            Base64 (RFC 4648)        |
|  4.0 bits/char          5.0 bits/char             ~5.858 bits/char       6.0 bits/char            |
|  [Low Density / High]   [Case-Insensitive]        [Human Error Defense]  [High Density / URL Raw] |
+---------------------------------------------------------------------------------------------------+

import crypto from 'crypto';

export class Base58Codec {
  public static readonly BITCOIN_ALPHABET =
    '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';

  /**
   * Encodes a raw Uint8Array into a standard Base58 string.
   */
  public static encode(bytes: Uint8Array, alphabet = this.BITCOIN_ALPHABET): string {
    if (bytes.length === 0) return '';

    // 1. Count leading zero bytes (0x00)
    let leadingZeros = 0;
    while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) {
      leadingZeros++;
    }

    // 2. Convert byte array into BigInt
    let intVal = BigInt(0);
    for (let i = 0; i < bytes.length; i++) {
      intVal = (intVal << BigInt(8)) + BigInt(bytes[i]);
    }

    // 3. Repeated division modulo 58
    let result = '';
    const radix = BigInt(58);

    while (intVal > BigInt(0)) {
      const mod = Number(intVal % radix);
      intVal = intVal / radix;
      result = alphabet[mod] + result;
    }

    // 4. Prepend leading '1' characters for each leading zero byte
    const leader = alphabet[0];
    return leader.repeat(leadingZeros) + result;
  }

  /**
   * Decodes a Base58 string back into a raw Uint8Array.
   */
  public static decode(str: string, alphabet = this.BITCOIN_ALPHABET): Uint8Array {
    if (str.length === 0) return new Uint8Array(0);

    // 1. Count leading leader characters ('1')
    const leader = alphabet[0];
    let leadingZeros = 0;
    while (leadingZeros < str.length && str[leadingZeros] === leader) {
      leadingZeros++;
    }

    // 2. Convert Base58 string to BigInt
    let intVal = BigInt(0);
    const radix = BigInt(58);

    for (let i = 0; i < str.length; i++) {
      const char = str[i];
      const charIndex = alphabet.indexOf(char);
      if (charIndex === -1) {
        throw new Error(Invalid Base58 character encountered: "${char}" at index ${i});
      }
      intVal = intVal * radix + BigInt(charIndex);
    }

    // 3. Convert BigInt into byte array
    const hex = intVal.toString(16);
    const paddedHex = hex.length % 2 === 0 ? hex : '0' + hex;
    const bytes: number[] = [];

    if (intVal > BigInt(0)) {
      for (let i = 0; i < paddedHex.length; i += 2) {
        bytes.push(parseInt(paddedHex.substr(i, 2), 16));
      }
    }

    // 4. Combine leading zeros and decoded bytes
    const result = new Uint8Array(leadingZeros + bytes.length);
    result.fill(0, 0, leadingZeros);
    result.set(bytes, leadingZeros);

    return result;
  }

  /**
   * Encodes a payload with a version byte and double SHA-256 checksum (Base58Check).
   */
  public static encodeCheck(versionByte: number, payload: Uint8Array): string {
    const versioned = new Uint8Array(1 + payload.length);
    versioned[0] = versionByte;
    versioned.set(payload, 1);

    // Double SHA-256
    const hash1 = crypto.createHash('sha256').update(versioned).digest();
    const hash2 = crypto.createHash('sha256').update(hash1).digest();
    const checksum = hash2.subarray(0, 4);

    const fullPayload = new Uint8Array(versioned.length + 4);
    fullPayload.set(versioned, 0);
    fullPayload.set(checksum, versioned.length);

    return this.encode(fullPayload);
  }

  /**
   * Decodes a Base58Check string, validating the 4-byte checksum.
   */
  public static decodeCheck(str: string): { version: number; payload: Uint8Array } {
    const decoded = this.decode(str);
    if (decoded.length < 5) {
      throw new Error('Base58Check payload too short to contain version and checksum.');
    }

    const payloadWithVersion = decoded.subarray(0, decoded.length - 4);
    const providedChecksum = decoded.subarray(decoded.length - 4);

    // Verify double SHA-256 checksum
    const hash1 = crypto.createHash('sha256').update(payloadWithVersion).digest();
    const hash2 = crypto.createHash('sha256').update(hash1).digest();
    const calculatedChecksum = hash2.subarray(0, 4);

    for (let i = 0; i < 4; i++) {
      if (providedChecksum[i] !== calculatedChecksum[i]) {
        throw new Error('Base58Check checksum validation failed! Typographical error detected.');
      }
    }

    return {
      version: payloadWithVersion[0],
      payload: payloadWithVersion.subarray(1)
    };
  }
}