chore: deprecate bech32 addresses (#3411)

Author: maschad

.changeset/late-pugs-carry.md

@@ -0,0 +1,7 @@
+---
+"@fuel-ts/interfaces": patch
+"@fuel-ts/address": patch
+"@fuel-ts/errors": patch
+---
+
+chore: deprecate bech32 addresses

CONTRIBUTING.md

@@ -246,6 +246,9 @@ The e2e test can be found at:
 
 The Bech32 address of this wallet is `fuel1x33ajpj0jy5p2wcqqu45e32r75zrwfeh6hwqfv5un670rv4p0mns58enjg`. This address can be funded via the [faucet](https://faucet-testnet.fuel.network/).
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+
 If you want to run an e2e test locally, you can provide your own wallet address and private key. For obvious security reasons, the private key should not be shared.
 
 These can be overridden by generating an environment file:

apps/docs/src/guide/contracts/managing-deployed-contracts.md

@@ -8,6 +8,9 @@ The `contractId` property from the [`Contract`](../../api/Program/Contract.md) c
 
 The [`Address`](../../api/Address/Address.md) class wraps all methods from the [`AbstractAddress`](../../api/Interfaces/AbstractAddress.md) class and adds a single property: `bech32Address`. This property is a string encoded in [`Bech32`](../types/bech32.md) format, recognizable by the human-readable prefix `fuel` followed by the separator `1`.
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated; please switch to B256 format, for more details see [here](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256).
+
 When you log the `contractId` property of an instantiated Contract using `console.log`, the output appears as follows:
 
 ```console

apps/docs/src/guide/types/address.md

@@ -24,6 +24,9 @@ To create an [`Address`](../../api/Address/Address.md) from a `Bech32` address,
 
 <<< @/../../docs-snippets2/src/types/address/creating-an-address.ts#full{ts:line-numbers}
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+
 ### From a Public Key
 
 To create an [`Address`](../../api/Address/Address.md) from a public key, use the following code snippet:

apps/docs/src/guide/types/bech32.md

@@ -1,5 +1,8 @@
 # `Bech32`
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+
 The SDK uses the `Bech32` type as the core property of the [`Address`](../../api/Address/Address.md) class, specifically through the `bech32Address` property.
 
 Originally designed for Bitcoin, the `Bech32` format offers numerous advantages such as enhanced error detection, simplified integrations, and improved compatibility with future upgrades. Given these benefits, the [`Address`](../../api/Address/Address.md) class is constructed around the `Bech32` type.

apps/docs/src/guide/utilities/address-conversion.md

@@ -6,6 +6,9 @@ The Fuel Network uses the [`Bech32`](../types/bech32.md) address format for its
 
 <<< @/../../docs-snippets2/src/types/bech32.ts#addresses-1{ts:line-numbers}
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+
 However, a hexlified [Bits256](../types/bits256.md) (hex) is another common address format; an example can be seen below:
 
 <<< @/../../docs-snippets2/src/types/evm-address/creating-an-evm.ts#snippet-2{ts:line-numbers}

packages/address/README.md

@@ -4,6 +4,9 @@
 
 This module contains the utilities for encoding and decoding address and contract ids between Bech32 and other address formats.
 
+> [!NOTE] Note
+> `Bech32` addresses like `fuel1..` are now deprecated. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+
 # Table of contents
 
 - [Documentation](#documentation)

packages/address/src/address.ts

@@ -30,21 +30,30 @@ import {
  */
 export default class Address extends AbstractAddress {
   // #region address-2
+  /**
+   * @deprecated
+   * Type `Bech32Address` is now deprecated, as is this property. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+   */
   readonly bech32Address: Bech32Address;
   // #endregion address-2
 
   /**
-   * @param address - A Bech32 address
+   * @param address - A Bech32 address or B256 address
    */
-  constructor(address: Bech32Address) {
+  constructor(address: Bech32Address | B256Address) {
     super();
-    this.bech32Address = normalizeBech32(address);
 
-    if (!isBech32(this.bech32Address)) {
-      throw new FuelError(
-        FuelError.CODES.INVALID_BECH32_ADDRESS,
-        `Invalid Bech32 Address: ${address}.`
-      );
+    if (isB256(address)) {
+      this.bech32Address = toBech32(address);
+    } else {
+      this.bech32Address = normalizeBech32(address as Bech32Address);
+
+      if (!isBech32(this.bech32Address)) {
+        throw new FuelError(
+          FuelError.CODES.INVALID_BECH32_ADDRESS,
+          `Invalid Bech32 Address: ${this.bech32Address}.`
+        );
+      }
     }
   }
 
@@ -60,7 +69,8 @@ export default class Address extends AbstractAddress {
 
   /**
    * Returns the `bech32Address` property
-   *
+   * @deprecated
+   * Type `Bech32Address` is now deprecated, as is this method. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
    * @returns The `bech32Address` property
    */
   toAddress(): Bech32Address {
@@ -69,7 +79,6 @@ export default class Address extends AbstractAddress {
 
   /**
    * Converts and returns the `bech32Address` property to a 256 bit hash string
-   *
    * @returns The `bech32Address` property as a 256 bit hash string
    */
   toB256(): B256Address {
@@ -78,16 +87,14 @@ export default class Address extends AbstractAddress {
 
   /**
    * Converts and returns the `bech32Address` property to a byte array
-   *
    * @returns The `bech32Address` property as a byte array
    */
   toBytes(): Uint8Array {
     return getBytesFromBech32(this.bech32Address);
   }
 
   /**
-   * Converts
-   *
+   * Converts the `bech32Address` property to a 256 bit hash string
    * @returns The `bech32Address` property as a 256 bit hash string
    */
   toHexString(): B256Address {
@@ -105,16 +112,14 @@ export default class Address extends AbstractAddress {
 
   /**
    * Converts and returns the `bech32Address` property as a string
-   *
-   * @returns The `bech32Address` property as a string
+   * @returns The `bech32Address` property as a JSON string
    */
   toJSON(): string {
     return this.bech32Address;
   }
 
   /**
    * Clears the first 12 bytes of the `bech32Address` property and returns it as a `EvmAddress`
-   *
    * @returns The `bech32Address` property as an {@link EvmAddress | `EvmAddress`}
    */
   toEvmAddress(): EvmAddress {
@@ -126,9 +131,8 @@ export default class Address extends AbstractAddress {
   }
 
   /**
-   * Wraps the `bech32Address` property and returns as an `AssetId`.
-   *
-   * @returns The `bech32Address` property as an {@link AssetId | `AssetId`}
+   * Wraps the B256 property and returns as an `AssetId`.
+   * @returns The B256 property as an {@link AssetId | `AssetId`}
    */
   toAssetId(): AssetId {
     return {
@@ -137,17 +141,15 @@ export default class Address extends AbstractAddress {
   }
 
   /**
-   * returns the address `checksum` as a string
-   *
-   * @returns The value of `bech32Address` property
+   * Wraps the B256 address `checksum` and returns it as a string
+   * @returns The B256 address `checksum` as a string
    */
   override valueOf(): string {
     return this.toChecksum();
   }
 
   /**
    * Compares this the `bech32Address` property to another for direct equality
-   *
    * @param other - Another address to compare against
    * @returns The equality of the comparison
    */

packages/address/src/utils.ts

@@ -23,7 +23,8 @@ export const FUEL_BECH32_HRP_PREFIX = 'fuel';
 
 /**
  * Decodes a Bech32 address string into Decoded
- *
+ * @deprecated
+ * Type `Bech32Address` is now deprecated, as is this function. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
  * @hidden
  */
 export function fromBech32(address: Bech32Address): Decoded {
@@ -32,7 +33,8 @@ export function fromBech32(address: Bech32Address): Decoded {
 
 /**
  * Converts a B256 address string into Bech32
- *
+ * @deprecated
+ * Type `Bech32Address` is now deprecated, as is this function. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
  * @hidden
  */
 export function toBech32(address: B256Address): Bech32Address {
@@ -44,7 +46,8 @@ export function toBech32(address: B256Address): Bech32Address {
 
 /**
  * Determines if a given string is Bech32 format
- *
+ * @deprecated
+ * Type `Bech32Address` is now deprecated, as is this function. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
  * @hidden
  */
 export function isBech32(address: BytesLike): boolean {
@@ -84,7 +87,8 @@ export function isEvmAddress(address: string): boolean {
 
 /**
  * Takes a Bech32 address and returns the byte data
- *
+ * @deprecated
+ * The `bech32Address` is now deprecated. Please migrate to B256 format (see https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256 for more details) as this will be the standard going forward.
  * @hidden
  */
 export function getBytesFromBech32(address: Bech32Address): Uint8Array {
@@ -93,7 +97,6 @@ export function getBytesFromBech32(address: Bech32Address): Uint8Array {
 
 /**
  * Converts a Bech32 address string into B256
- *
  * @hidden
  */
 export function toB256(address: Bech32Address): B256Address {

packages/errors/src/error-codes.ts

@@ -25,7 +25,12 @@ export enum ErrorCode {
   WORKSPACE_NOT_DETECTED = 'workspace-not-detected',
 
   // address
+  /**
+   * @deprecated
+   * Type `Bech32Address` is now deprecated, as is this constant. Use `B256` addresses instead. ([help](https://docs.fuel.network/docs/specs/abi/argument-encoding/#b256))
+   */
   INVALID_BECH32_ADDRESS = 'invalid-bech32-address',
+
   INVALID_EVM_ADDRESS = 'invalid-evm-address',
   INVALID_B256_ADDRESS = 'invalid-b256-address',