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

# For End Users

> How to consume proven historical data from Satellite contracts

If you are integrating Satellite into an application contract, most of your usage is through read functions on the `ISatellite` interface.

## Core read functions

The three most common reads are:

* `accountField(chainId, blockNumber, account, field) -> bytes32`
* `storageSlot(chainId, blockNumber, account, slot) -> bytes32`
* `timestamp(chainId, timestamp) -> uint256`

Use these when you need historical account fields, storage values, or "latest block at a given time" lookups.

## Safe vs reverting reads

Most Satellite read functions come in two versions:

* `...Safe(...)` returns `(exists, value)` and does not revert on missing data.
* Non-`Safe` variant returns the value directly and reverts when data is not present.

This pattern lets you choose between explicit existence checks and strict failure behavior.

## Data lifecycle for a read

Your contract reads only facts already saved in Satellite. The typical lifecycle is:

1. A proof workflow verifies block/account/storage data against Satellite MMR commitments.
2. Verified fields are written into Satellite storage.
3. Your contract reads the saved values by chain ID and block number.

In managed flows, [Storage Proof API](/storage-proofs-api/introduction) handles step 1 and the related proof plumbing.

## Example integration path

To consume the interface in Solidity:

```bash theme={null}
npm install https://github.com/HerodotusDev/satellite
```

```solidity theme={null}
import { ISatellite } from "@HerodotusDev/satellite/solidity/src/interfaces/ISatellite.sol";
```

You can also install with Foundry and import from `lib/satellite/...`.

## Practical usage patterns

* Historical token balance checks for voting and governance snapshots.
* Storage-slot based eligibility logic (airdrops, allowlists, retroactive rewards).
* Time-based historical reads using `timestamp(...)` first, then account/storage lookups.

## Important expectation

Satellite is a verification and data-access contract layer, not a general-purpose query engine.

If your app needs broad candidate discovery (for example, "all addresses matching X"), do that off-chain first, then verify and consume only the needed facts on-chain.