Difference between revisions of "VarInt"
(Changed example hex values from big endian to little endian.)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
A [[varint]] or "Variable Integer" is an integer format used widely in Bitcoin to indicate the lengths of fields within transaction and block data.
+
A VarInt or "Variable Integer" is an [[integer]] format used widely in Bitcoin to indicate the lengths of fields within transaction, block and peer-to-peer network data.
  
−
A VarInt is a variable length field 1, 3, 5 or 9 bytes in length dependent on the size of the object being defined. The VarInt format is used as it is space efficient over simply using an 8-byte field where variable length objects are used.
+
A VarInt is a variable length field 1, 3, 5 or 9 bytes in length dependent on the size of the object being defined. The VarInt format is used as it is space efficient over simply using an 8-byte field where variable length objects are used. VarInt values are almost always represented in little endian.  
  
 
==Using VarInts==
 
==Using VarInts==
  
−
When expressing an integer value less than or equal to <code>0xFC</code> (252) the value itself can be used.
+
When expressing an integer between zero and <code>0xFC</code> (252) the value itself can be used and expressed in uint8_t format.
  
−
When expressing an integer value greater than <code>0xFC</code> but less than or equal to <code>0xFFFF</code> (65,535), the varint is <code>0xFDXXXX</code> where XXXX represents the two byte integer
+
When expressing an integer value greater than <code>0xFC</code> but less than or equal to <code>0xFFFF</code> (65,535), the varint is <code>0xFDXXXX</code> where XXXX represents the two byte integer in uint16_t format.
  
−
When expressing an integer value greater than <code>0xFFFF</code> but less than or equal to <code>0xFFFFFFFF</code> (4,294,967,295), the varint is <code>0xFEXXXXXXXX</code> where XXXXXXXX represents the 4 byte integer
+
When expressing an integer value greater than <code>0xFFFF</code> but less than or equal to <code>0xFFFFFFFF</code> (4,294,967,295), the varint is <code>0xFEXXXXXXXX</code> where XXXXXXXX represents the 4 byte integer in uint32_t format.
  
−
When expressing an integer value greater than <code>0xFFFFFFFF</code> but less than or equal to <code>0xFFFFFFFFFFFFFFFF</code> (18,446,744,073,709,551,615), the varint is <code>0xFFXXXXXXXXXXXXXXXX</code> where XXXXXXXXXXXXXXXX represents the 8 byte integer
+
When expressing an integer value greater than <code>0xFFFFFFFF</code> but less than or equal to <code>0xFFFFFFFFFFFFFFFF</code> (18,446,744,073,709,551,615), the varint is <code>0xFFXXXXXXXXXXXXXXXX</code> where XXXXXXXXXXXXXXXX represents the 8 byte integer in uint64_t format.
  
−
===Examples===
+
===References with Examples===
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Value
+
! Value Range <br> <br> Example Value
−
! Size
+
! Size Range <br> <br> Example Size
−
! VarInt
+
! VarInt Format <br> <br> Example VarInt
 
|-
 
|-
−
| 187 (<code>0xBB</code>)
+
| 0 <= Value <= 252 (<code>0xFC</code>) <br> <br> e.g. 187 (<code>0xBB</code>)
−
| 1 byte (less than or equal to <code>0xFC</code>)
+
| 1 byte <br> <br> 1 byte
−
| <code>0xBB</code>
+
| uint8_t <br> <br> <code>0xBB</code>
 
|-
 
|-
−
| 255 (<code>0xFF</code>)
+
| 253 <= Value <= 65,535 (<code>0xFFFF</code>) <br> <br> e.g. 255 (<code>0xFF</code>) <br> <br> e.g. 13,337 (<code>0x3419</code>)
−
| 1 byte (greater than <code>0xFC</code>)
+
| 1 - 2 bytes <br> <br> 1 byte but greater than <code>0xFC</code> <br> <br> 2 bytes
−
| <code>0xFD00FF</code>
+
| 0xFD + number as uint16_t <br> <br> <code>0xFDFF00</code> <br> <br> <code>0xFD1934</code>
 
|-
 
|-
−
| 13,337 (<code>0x3419</code>)
+
| 65,536 <= Value <= ‭4,294,967,295‬ (<code>0xFFFFFFFF</code>) <br> <br> e.g. 14,435,729 (<code>0xDC4591</code>) <br> <br> e.g. 134,250,981 (<code>0x80081E5</code>)
−
| 2 bytes
+
| 3 - 4 bytes <br> <br> 3 bytes <br> <br> 4 bytes
−
| <code>0xFD3419</code>
+
| 0xFE + number as uint32_t  <br> <br> <code>0xFE9145DC00</code> <br> <br> <code>0xFEE5810008</code>
 
|-
 
|-
−
| 14,435,729 (<code>0xDC4591</code>)
+
| 4,294,967,296 <= value <= ‭18,446,744,073,709,551,615 (<code>0xFFFFFFFFFFFFFFFF</code>) <br> <br> e.g.198,849,843,832,919 (<code>0xB4DA564E2857</code>) <br> <br> e.g. 5,473,425,651,754,713,432 (<code>0x‭4BF583A17D59C158‬</code>)
−
| 3 bytes
+
| 5 - 8 bytes <br> <br> 6 bytes <br> <br> 8 bytes
−
| <code>0xFE00DC4591</code>
+
| 0xFF + number as uint64_t  <br> <br> <code>0xFF57284E56DAB40000</code>  <br> <br> <code>0xFF58C1597DA183F54B</code>
−
|-
 
−
| 134,250,981 (<code>0x80081E5</code>)
 
−
| 4 bytes
 
−
| <code>0xFE080081E5</code>
 
−
|-
 
−
| 198,849,843,832,919 (<code>0xB4DA564E2857</code>)
 
−
| 6 bytes
 
−
| <code>0xFF0000B4DA564E2857</code>
 
−
|-
 
−
| 5,473,425,651,754,713,432 (<code>0x‭4BF583A17D59C158‬</code>)
 
−
| 8 bytes
 
−
| <code>0xFF4BF583A17D59C158</code>
 
 
|}
 
|}

Latest revision as of 13:33, 25 October 2023

A VarInt or "Variable Integer" is an integer format used widely in Bitcoin to indicate the lengths of fields within transaction, block and peer-to-peer network data.

A VarInt is a variable length field 1, 3, 5 or 9 bytes in length dependent on the size of the object being defined. The VarInt format is used as it is space efficient over simply using an 8-byte field where variable length objects are used. VarInt values are almost always represented in little endian.

Using VarInts

When expressing an integer between zero and 0xFC (252) the value itself can be used and expressed in uint8_t format.

When expressing an integer value greater than 0xFC but less than or equal to 0xFFFF (65,535), the varint is 0xFDXXXX where XXXX represents the two byte integer in uint16_t format.

When expressing an integer value greater than 0xFFFF but less than or equal to 0xFFFFFFFF (4,294,967,295), the varint is 0xFEXXXXXXXX where XXXXXXXX represents the 4 byte integer in uint32_t format.

When expressing an integer value greater than 0xFFFFFFFF but less than or equal to 0xFFFFFFFFFFFFFFFF (18,446,744,073,709,551,615), the varint is 0xFFXXXXXXXXXXXXXXXX where XXXXXXXXXXXXXXXX represents the 8 byte integer in uint64_t format.

References with Examples

Value Range

Example Value 		Size Range

Example Size 		VarInt Format

Example VarInt
0 <= Value <= 252 (0xFC)

e.g. 187 (0xBB) 		1 byte

1 byte 		uint8_t

0xBB
253 <= Value <= 65,535 (0xFFFF)

e.g. 255 (0xFF)

e.g. 13,337 (0x3419) 		1 - 2 bytes

1 byte but greater than 0xFC

2 bytes 		0xFD + number as uint16_t

0xFDFF00

0xFD1934
65,536 <= Value <= ‭4,294,967,295‬ (0xFFFFFFFF)

e.g. 14,435,729 (0xDC4591)

e.g. 134,250,981 (0x80081E5) 		3 - 4 bytes

3 bytes

4 bytes 		0xFE + number as uint32_t

0xFE9145DC00

0xFEE5810008
4,294,967,296 <= value <= ‭18,446,744,073,709,551,615 (0xFFFFFFFFFFFFFFFF)

e.g.198,849,843,832,919 (0xB4DA564E2857)

e.g. 5,473,425,651,754,713,432 (0x‭4BF583A17D59C158‬) 		5 - 8 bytes

6 bytes

8 bytes 		0xFF + number as uint64_t

0xFF57284E56DAB40000

0xFF58C1597DA183F54B
Retrieved from "https://wiki.bitcoinsv.io/index.php?title=VarInt&oldid=3118"