From 1cef3277200df49ee99e43dcdccb05c6d1d491e2 Mon Sep 17 00:00:00 2001 From: Brian M Hamlin Date: Thu, 18 Mar 2021 15:06:13 -0700 Subject: [PATCH] first pass format --- spec/cBITS_provisional_spec.md | 46 +++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/spec/cBITS_provisional_spec.md b/spec/cBITS_provisional_spec.md index 5f70e35..e49f5b5 100644 --- a/spec/cBITS_provisional_spec.md +++ b/spec/cBITS_provisional_spec.md @@ -12,14 +12,14 @@ Replaces: None -==Abstract== +## Abstract ## Notes on Compact BITS Format -Objective: show BITS (4 byte) compact representation of a uint256 input +**Objective**: show BITS (4 byte) compact representation of a uint256 input -Given: Very large integer numbers may be represented in a custom eight-byte, 256 bit structure uint256. A second format is also defined using a standard four-byte 32bit unsigned integer. This compact BITS format packs up to three bytes of value from uint256, and uses the remaining most-significant byte to store a count of the total number of bytes in the expanded number. The compact BITS format delivers a lot less precision than uint256 but is portable in a standardized way. This page explains conversion from uint256 to the compact BITS format, in order to clarify the rules for implementing conversion for common computer languages and minimize the chance of serious differences between implementation. +**Given**: Very large integer numbers may be represented in a custom eight-byte, 256 bit structure uint256. A second format is also defined using a standard four-byte 32bit unsigned integer. This compact BITS format packs up to three bytes of value from uint256, and uses the remaining most-significant byte to store a count of the total number of bytes in the expanded number. The compact BITS format delivers a lot less precision than uint256 but is portable in a standardized way. This page explains conversion from uint256 to the compact BITS format, in order to clarify the rules for implementing conversion for common computer languages and minimize the chance of serious differences between implementation. Conversion Rules: Take three bytes from uint256, starting with the most-significant non-zero bytes (left-most). The top bit of the three bytes is reserved for a sign bit (seldom used in practice). Conversion code must take care to keep the sign bit clear in a compact result, which often means retaining less value from the source uint256 as shown below. A single byte in compact BITS is used to keep the length of the expanded results. @@ -27,7 +27,7 @@ Conversion Rules: Take three bytes from uint256, starting with the most-signific -- -Example 1 convert src to dst (28 bytes of data following four bytes of zero) +**Example 1** convert src to dst (28 bytes of data following four bytes of zero) given: 0x000000008cc30f97a647313fe0cad97a647313fe0cad97a647313fe0cad97a64 -------------------------------------------------------------------------- @@ -37,11 +37,11 @@ Step) extract the most-significant three bytes of uint256, store as resInt inCount = 28 (0x1C) -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | resInt | Octets | 140 (0x8C) | 195 (0xC3) | 15 (0x0F) | -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | Bits | 1 0 0 0 1 1 0 0 | 1 1 0 0 0 0 1 1 | 0 0 0 0 1 1 1 1 | -+-----------------+-----------------+-----------------+-----------------+ +|-----------------|-----------------|-----------------|-----------------| Step) test the high bit of the left-most, non-zero byte of input uint256 ; if set, @@ -50,35 +50,35 @@ Step) test the high bit of the left-most, non-zero byte of input uint256 ; inCount = 29 (0x1D) -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | resInt | Octets | 0 (0x00) | 140 (0x8C) | 195 (0xC3) | -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | Bits | 0 0 0 0 0 0 0 0 | 1 0 0 0 1 1 0 0 | 1 1 0 0 0 0 1 1 | -+-----------------+-----------------+-----------------+-----------------+ +|-----------------|-----------------|-----------------|-----------------| Step) multiply inCount by 2**24, resulting in a 32bit integer (left shift) inCount shifted left by three (3) bytes -+---------+--------+-----------------+-----------------+-----------------+-----------------+ +|---------|--------|-----------------|-----------------|-----------------|-----------------| | inCount | Octets | 29 (0x1D) | 0 (0x00) | 0 (0x00) | 0 (0x00) | -+---------+--------+-----------------+-----------------+-----------------+-----------------+ +|---------|--------|-----------------|-----------------|-----------------|-----------------| | Bits | 0 0 0 1 1 1 0 1 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | -+------------------+-----------------+-----------------+-----------------+-----------------+ +|------------------|-----------------|-----------------|-----------------|-----------------| Step) combine inCount and resInt (logical OR) to make the final Compact BITS (CBITS) -+-------+--------+-----------------+-----------------+-----------------+-----------------+ +|-------|--------|-----------------|-----------------|-----------------|-----------------| | CBITS | Octets | 29 (0x1D) | 0 (0x00) | 140 (0x8C) | 195 (0xC3) | -+-------+--------+-----------------+-----------------+-----------------+-----------------+ +|-------|--------|-----------------|-----------------|-----------------|-----------------| | Bits | 0 0 0 1 1 1 0 1 | 0 0 0 0 0 0 0 0 | 1 0 0 0 1 1 0 0 | 1 1 0 0 0 0 1 1 | -+----------------+-----------------+-----------------+-----------------+-----------------+ +|----------------|-----------------|-----------------|-----------------|-----------------| Expanded Result from compact BITS 0x8cc30000000000000000000000000000000000000000000000000000 -- -Example 2 convert src to dst (29 bytes of data following three bytes of zero) +**Example 2** convert src to dst (29 bytes of data following three bytes of zero) given: 0x0000000128a0e4b1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1fb1 -------------------------------------------------------------------------- @@ -88,11 +88,11 @@ Step) extract the most-significant three bytes of uint256, store as resInt inCount = 29 (0x1D) -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | resInt | Octets | 1 (0x01) | 40 (0x28) | 160 (0xA0) | -+--------+--------+-----------------+-----------------+-----------------+ +|--------|--------|-----------------|-----------------|-----------------| | Bits | 0 0 0 0 0 0 0 1 | 0 0 1 0 1 0 0 0 | 1 0 1 0 0 0 0 0 | -+-----------------+-----------------+-----------------+-----------------+ +|-----------------|-----------------|-----------------|-----------------| Step) test the high bit of the left-most, non-zero byte of input uint256 ; bit not set @@ -100,11 +100,11 @@ Step) multiply inCount by 2**24, resulting in a 32bit integer (left shift) inCount shifted left by three (3) bytes -+---------+--------+-----------------+-----------------+-----------------+-----------------+ +|---------|--------|-----------------|-----------------|-----------------|-----------------| | inCount | Octets | 29 (0x1D) | 0 (0x00) | 0 (0x00) | 0 (0x00) | -+---------+--------+-----------------+-----------------+-----------------+-----------------+ +|---------|--------|-----------------|-----------------|-----------------|-----------------| | Bits | 0 0 0 1 1 1 0 1 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | 0 0 0 0 0 0 0 0 | -+------------------+-----------------+-----------------+-----------------+-----------------+ +|------------------|-----------------|-----------------|-----------------|-----------------| Step) combine inCount and resInt (logical OR) to make the final Compact BITS (CBITS)