clarify HASH256 process in Base58Check encoding description

massalabs · Dec 11, 2024 · 8d5c2b0 · 8d5c2b0
1 parent 6662c96
commit 8d5c2b0
Showing 1 changed file with 33 additions and 22 deletions.
diff --git a/docs/learn/operation-format-execution.mdx b/docs/learn/operation-format-execution.mdx
@@ -96,11 +96,13 @@ The ID of an operation has the following UTF-8 ASCII-compatible text representat
 Note that the base58check encoding is the same one as the one used by bitcoin but without version number as it is already included in the underlying binary serialization of the operation ID.
 
 Here is the entire encoding process for an operation ID in text format:
-* serialize the operation ID in binary format (see above)
-* compute the SHA256 hash of the binary serialization
-* append the first 4 bytes of the sha256 hash at the end of the binary serialization of the ID. This is used as a checksum to detect typing errors as operation IDs are also meant to be written on paper by humans.
-* encode the resulting byte array using the base alphabet `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar looking characters (eg 0 vs O) are excluded to avoid human confusion.
-* prepend the letter 'O'
+1. **Serialize the operation ID** in binary format (see above).
+2. **Compute the HASH256 of the binary serialization**, which involves performing **SHA256 twice consecutively**:
+    - First, compute the SHA256 hash of the binary serialization.
+    - Then compute the SHA256 hash of the result from the first step.
+3. **Append the first 4 bytes of the resulting HASH256** as a checksum to the end of the binary serialization of the ID. This checksum helps detect typing errors, as operation IDs are also meant to be written on paper by humans.
+4. **Encode the resulting byte array** using the Base58 alphabet: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar-looking characters (e.g., `0` vs `O`) are excluded to avoid human confusion.
+5. **Prepend the letter 'O'**.
 
 Legality checks performed on text deserialization:
 * the text must be valid UTF-8 and ASCII with only alphanumeric characters
@@ -181,14 +183,17 @@ Secret keys have the following UTF-8 ASCII-compatible text representation:
 |                       | (see above)                                                                                           | (18 to 62 bytes)                            |
 +-----------------------+-------------------------------------------------------------------------------------------------------+---------------------------------------------+
 
-Note that the base58check encoding is the same one as the one used by bitcoin but without version number as it is already included in the underlying binary serialization of the secret key.
+Note that the Base58Check encoding is the same one as used by Bitcoin, but without a version number as it is already included in the underlying binary serialization of the secret key.
 
 Here is the entire encoding process for a secret key in text format:
-* serialize the secret key in binary format (see above)
-* compute the SHA256 hash of the binary serialization
-* append the first 4 bytes of the sha256 hash at the end of the binary serialization of the key. This is used as a checksum to detect typing errors as secret keys are also meant to be written on paper by humans.
-* encode the resulting byte array using the base alphabet `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar looking characters (eg 0 vs O) are excluded to avoid human confusion.
-* prepend the letter 'S'
+
+1. **Serialize the secret key** in binary format (see above).
+2. **Compute the HASH256 of the binary serialization**, which involves performing **SHA256 twice consecutively**:
+    - First, compute the SHA256 hash of the binary serialization.
+    - Then compute the SHA256 hash of the result from the first step.
+3. **Append the first 4 bytes of the resulting HASH256** as a checksum to the end of the binary serialization of the key. This checksum helps detect typing errors, as secret keys are also meant to be written on paper by humans.
+4. **Encode the resulting byte array** using the Base58 alphabet: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar-looking characters (e.g., `0` vs `O`) are excluded to avoid human confusion.
+5. **Prepend the letter 'S'**.
 
 Legality checks performed on text deserialization:
 * the text must be valid UTF-8 and ASCII with only alphanumeric characters
@@ -239,14 +244,17 @@ Public keys have the following UTF-8 ASCII-compatible text representation:
 |                       | See above.                                                                                            | 18 to 62 bytes                              |
 +-----------------------+-------------------------------------------------------------------------------------------------------+---------------------------------------------+
 
-Note that the base58check encoding is the same one as the one used by bitcoin but without version number as it is already included in the underlying binary serialization of the public key.
+Note that the Base58Check encoding is the same one as used by Bitcoin, but without a version number as it is already included in the underlying binary serialization of the public key.
 
 Here is the entire encoding process for a public key in text format:
-* serialize the public key in binary format (see above)
-* compute the SHA256 hash of the binary serialization
-* append the first 4 bytes of the sha256 hash at the end of the binary serialization of the key. This is used as a checksum to detect typing errors as public keys are also meant to be written on paper by humans.
-* encode the resulting byte array using the base alphabet `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar looking characters (eg 0 vs O) are excluded to avoid human confusion.
-* prepend the letter 'P'
+
+1. **Serialize the public key** in binary format (see above).
+2. **Compute the HASH256 of the binary serialization**, which involves performing **SHA256 twice consecutively**:
+    - First, compute the SHA256 hash of the binary serialization.
+    - Then compute the SHA256 hash of the result from the first step.
+3. **Append the first 4 bytes of the resulting HASH256** as a checksum to the end of the binary serialization of the key. This checksum helps detect typing errors, as public keys are also meant to be written on paper by humans.
+4. **Encode the resulting byte array** using the Base58 alphabet: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar-looking characters (e.g., `0` vs `O`) are excluded to avoid human confusion.
+5. **Prepend the letter 'P'**.
 
 Legality checks performed on text deserialization:
 * the text must be valid UTF-8 and ASCII with only alphanumeric characters
@@ -312,11 +320,14 @@ Text serialization of an address:
 +---------------------+----------------------------------------------------------------------------------------------------+-------------------------------------------+
 
 Here is the entire encoding process for an address in text format:
-* serialize the address in binary format but without the address category (only version then hash in the binary serialization described above)
-* compute the SHA256 hash of the binary serialization
-* append the first 4 bytes of the sha256 hash at the end of the binary serialization of the address. This is used as a checksum to detect typing errors as addresses are also meant to be written on paper by humans.
-* encode the resulting byte array using the base alphabet `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar looking characters (eg 0 vs O) are excluded to avoid human confusion.
-* prepend the prefix 'AU' for externally owned accounts or 'AS' for smart contracts
+
+1. **Serialize the address** in binary format but without the address category (only the version and hash are included in the binary serialization described above).
+2. **Compute the HASH256 of the binary serialization**, which involves performing **SHA256 twice consecutively**:
+    - First, compute the SHA256 hash of the binary serialization.
+    - Then compute the SHA256 hash of the result from the first step.
+3. **Append the first 4 bytes of the resulting HASH256** as a checksum to the end of the binary serialization of the address. This checksum helps detect typing errors, as addresses are also meant to be written on paper by humans.
+4. **Encode the resulting byte array** using the Base58 alphabet: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Similar-looking characters (e.g., `0` vs `O`) are excluded to avoid human confusion.
+5. **Prepend the prefix 'AU'** for externally owned accounts or **'AS'** for smart contracts.
 
 Legality checks performed on text deserialization:
 * the text must be valid UTF-8 and ASCII with only alphanumeric characters