> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloklake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data types

> How hashes, addresses, amounts and nested fields are encoded in Arrow and JSON, with conversion helpers.

Bloklake keeps values in their native binary form: an address is 20 bytes, a hash 32 bytes, an
amount a fixed-width big-endian integer. Arrow sends them as-is; JSON writes them as hex or
decimal strings.

## The types

| Arrow type | Used for | JSON |
| - | - | - |
| `UInt64` | block numbers, timestamps, gas, nonces, `chainId`, `v` | number |
| `UInt32` | `logIndex`, `transactionIndex` | number |
| `UInt8` | `status`, `type`, `yParity`, booleans (`1`/`0`) | number |
| `FixedSizeBinary(20)` | addresses | `0x` hex |
| `FixedSizeBinary(32)` | hashes, topics, roots, `r`, `s`; 256-bit amounts on Arbitrum | `0x` hex; amounts as decimal strings |
| `FixedSizeBinary(16)` | 128-bit amounts: `value`, `gasPrice`, `maxFeePerGas`, `effectiveGasPrice`, `baseFeePerGas`, `difficulty`, … | decimal string |
| `FixedSizeBinary(4)` | `sighash` | `0x` hex |
| `FixedSizeBinary(8)` | block `nonce` | `0x` hex |
| `FixedSizeBinary(256)` | `logsBloom` | `0x` hex |
| `Binary` | `input`, `data`, `extraData`, `retryData` | `0x` hex |
| `List<…>` | `uncles`, `blobVersionedHashes` | array |
| `List<Struct<…>>` | `withdrawals`, `accessList`, `authorizationList` | array of objects |

Every field and its exact type is in the field reference ([logs](https://docs.bloklake.com/api-reference/fields/logs.md),
[transactions](https://docs.bloklake.com/api-reference/fields/transactions.md), [blocks](https://docs.bloklake.com/api-reference/fields/blocks.md)), and
`GET /v1/schema` returns it as JSON.

## Amounts are big-endian integers

`value`, gas prices, fees and other amounts are unsigned big-endian integers: 16 bytes
(128-bit) for amounts that fit, 32 bytes (256-bit) for the Arbitrum retryable amounts that can
be as large as 2²⁵⁶ − 1. They're binary rather than `UInt64` because wei amounts overflow 64
bits (1 ETH is 10¹⁸ wei; `UInt64` tops out near 18.4 ETH).

```python Python theme={null}
value = int.from_bytes(row["value"], "big")            # Python ints are arbitrary precision
eth = value / 10**18

# a whole column with pyarrow
values = [int.from_bytes(b, "big") for b in table.column("value").to_pylist()]
```

```typescript TypeScript theme={null}
const toBigInt = (b: Uint8Array) => BigInt("0x" + Buffer.from(b).toString("hex") || "0");
const value = toBigInt(row.value);                     // 77n
```

```rust Rust theme={null}
use arrow::array::{Array, FixedSizeBinaryArray};

let col = batch.column_by_name("value").unwrap()
    .as_any().downcast_ref::<FixedSizeBinaryArray>().unwrap();
let v = u128::from_be_bytes(col.value(0).try_into()?);
```

## Addresses in topics

Indexed `address` arguments of an event are stored in a 32-byte topic, left-padded with zeros.
The address is the **last 20 bytes**:

```python Python theme={null}
sender = "0x" + row["topic1"][12:].hex()
```

```typescript TypeScript theme={null}
const sender = "0x" + Buffer.from(row.topic1.subarray(12)).toString("hex");
```

```python Polars theme={null}
df.with_columns(("0x" + pl.col("topic1").bin.slice(12).bin.encode("hex")).alias("from"))
```

To **filter** on an address in a topic, pad it the other way:
`"0x000000000000000000000000" + address[2:]`.

## Unsigned integers in JavaScript

apache-arrow returns `UInt64` columns as `bigint` (`19426000n`). Convert with `Number(x)` when
you know the value fits (block numbers and timestamps do), and keep `bigint` for gas totals you
add up.

## Nulls

Every nullable field can be `null` in a row. There are three different reasons:

1. **The value doesn't apply**: `to` on a contract creation, `baseFeePerGas` before London,
   `topic3` on an event with fewer indexed arguments, `contractAddress` on a normal call.
2. **The chain didn't report it**: `status` on pre-Byzantium transactions.
3. **The chain never has the field**: listed in `unavailable_fields`. See
   [Fields a chain doesn't have](https://docs.bloklake.com/querying/unavailable-fields.md).

Fields marked non-nullable in the reference are never null.

## Nested fields

`withdrawals`, `accessList` and `authorizationList` are lists of structs; `uncles` and
`blobVersionedHashes` are lists of hashes. They are not flattened.

```python theme={null}
w = block_row["withdrawals"]           # list of dicts in pyarrow's to_pylist()
total_gwei = sum(x["amount"] for x in w or [])
```

In JSON they're arrays of objects with snake\_case keys (`validator_index`, `storage_keys`).

## Booleans

`status`, `timeboosted` and `isSystemTx` are `UInt8`: `1` is true, `0` is false, `null` is
unknown or not applicable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.