TeachMeBitcoin

Custom Python VarInt Auditor

From TeachMeBitcoin, the free encyclopedia Reading time: 2 min

Custom Python VarInt Auditor

In this final guide, we will build a Python script that implements the CompactSize (VarInt) encoding and decoding logic. This auditor will help you verify the byte-length of counts in a raw transaction.

The VarInt Auditor

def encode_compact_size(i):
 """Encodes an integer into Bitcoin's CompactSize format."""
 if i < 253:
 return i.to_bytes(1, 'little')
 elif i <= 0xFFFF:
 return b'\xfd' + i.to_bytes(2, 'little')
 elif i <= 0xFFFFFFFF:
 return b'\xfe' + i.to_bytes(4, 'little')
 else:
 return b'\xff' + i.to_bytes(8, 'little')

def decode_compact_size(data):
 """Decodes a CompactSize byte string and returns (value, bytes_read)."""
 first = data[0]
 if first < 253:
 return first, 1
 elif first == 253:
 return int.from_bytes(data[1:3], 'little'), 3
 elif first == 254:
 return int.from_bytes(data[1:5], 'little'), 5
 else:
 return int.from_bytes(data[1:9], 'little'), 9

# --- Simulation ---

test_values = [10, 252, 253, 1000, 70000, 5000000000]

print("--- CompactSize (VarInt) Audit ---")
for val in test_values:
 encoded = encode_compact_size(val)
 decoded, size = decode_compact_size(encoded)

 print(f"[*] Value: {val:<12} | Hex: {encoded.hex(' '):<20} | Bytes: {size}")

 if val != decoded:
 print(f" [X] ERROR: Decode mismatch!")

# Scenario: Parsing a mock Input Count
print("\nScenario: Parsing Input Count from Raw Hex")
raw_data = bytes.fromhex("fd0002") # 512 in Little Endian with FD marker
count, s = decode_compact_size(raw_data)
print(f"[*] Parsed Count: {count} inputs (Read {s} bytes)")

How to Run the Auditor

  1. Ensure you have Python 3 installed.

  2. Copy the code into a file named varint_auditor.py.

  3. Run it using python3 varint_auditor.py.

Technical Takeaways

  1. Little Endian: Notice the 'little' parameter in the to_bytes and from_bytes functions. This is critical for matching the Bitcoin protocol.

  2. Slicing: In the decoder, we use data[1:3]. This skips the marker byte and reads only the relevant data.

  3. Boundary Awareness: The most important values to test are the boundaries: 252 and 253. These determine if the parser stays in "1-byte mode" or switches to "3-byte mode."

Congratulations! You have completed the Compact Size (VarInt) module. You now understand how Bitcoin keeps its transaction counts small, flexible, and extremely efficient.

☕ Help support TeachMeBitcoin

TeachMeBitcoin is an ad-free, open-source educational repository curated by a passionate team of Bitcoin researchers and educators for public benefit. If you found our articles helpful, please consider supporting our hosting and ongoing content updates with a clean donation:

Ethereum: 0x578417C51783663D8A6A811B3544E1f779D39A85
Bitcoin: bc1q77k9e95rn669kpzyjr8ke9w95zhk7pa5s63qzz
Solana: 4ycT2ayqeMucixj3wS8Ay8Tq9NRDYRPKYbj3UGESyQ4J
Address copied to clipboard!