Skip to main content

KV FastData Examples

Worked investigation​

Check one contract key, then follow its history​

Use this investigation when one contract storage key looks suspicious and you want the latest indexed value, the write history for that same key, and one final view_state check.

Strategy

Start with one exact key, widen only into that key’s history, then finish with one chain-state confirmation.

01get-latest-key gives the newest indexed row for the exact key you care about.

02get-history-key or history-by-key shows how that same key changed over time.

03RPC view_state is the final exact read when you need to compare index history with the chain right now.

Goal

  • Explain what this storage key looks like in the index, how it changed, and whether view_state agrees right now.
SurfaceEndpointHow we use itWhy we use it
Latest indexed valueKV FastData get-latest-keyFetch the newest indexed row for the exact key firstGives the fastest narrow answer before widening into history
Indexed key historyKV FastData get-history-key or history-by-keyPull the same key’s change history over timeShows whether the current value is stable, recent, or part of a suspicious sequence
Broader write patternKV FastData latest-by-account or history-by-predecessorCheck the account or predecessor if the one key is only part of a larger patternHelps explain whether the key changed by itself or as part of a bigger write set
Exact state checkRPC view_stateConfirm the current on-chain state once the indexed pattern is clearSeparates indexed storage history from the exact state the chain would return now

What a useful answer should include

  • the exact key and contract scope investigated
  • the latest indexed value and what changed in history
  • whether view_state matched the indexed current value

Exact key history shell walkthrough​

Use this when one fully qualified key is already known and you want to move cleanly from “what is the latest indexed row?” to “how did this exact key get here?”

What you're doing

  • Read one latest indexed key with the exact contract, predecessor, and key path.
  • Extract the exact key with jq.
  • Reuse that key in POST /v0/history to pull the write history for the same key.
KV_BASE_URL=https://kv.main.fastnear.com
CURRENT_ACCOUNT_ID=social.near
PREDECESSOR_ID=james.near
KEY='graph/follow/sleet.near'

ENCODED_KEY="$(jq -rn --arg key "$KEY" '$key | @uri')"

EXACT_KEY="$(
  curl -s "$KV_BASE_URL/v0/latest/$CURRENT_ACCOUNT_ID/$PREDECESSOR_ID/$ENCODED_KEY" \
    | tee /tmp/kv-latest.json \
    | jq -r '.entries[0].key'
)"

jq '{
  latest: (
    .entries[0]
    | {
        current_account_id,
        predecessor_id,
        block_height,
        key,
        value
      }
  )
}' /tmp/kv-latest.json

curl -s "$KV_BASE_URL/v0/history" \
  -H 'content-type: application/json' \
  --data "$(jq -nc --arg key "$EXACT_KEY" '{key: $key, limit: 10}')" \
  | jq '{
      page_token,
      entries: [
        .entries[]
        | {
            current_account_id,
            predecessor_id,
            block_height,
            value
          }
      ]
    }'

Why this next step?

The first lookup answers “what do we have right now?” Reusing the exact key in POST /v0/history answers “how did it get here?” If that result is too broad, narrow back down with GET History by Exact Key.

Common jobs​

Look up one exact key right now​

Start here

Next page if needed

Stop when

  • The latest indexed row already answers the storage question.

Switch when

  • The user needs the exact current chain state rather than the index. Move to View State.

Turn one exact key into a change history​

Start here

Next page if needed

Stop when

  • You can explain how the key changed over time.

Switch when

  • The user asks whether the latest indexed value matches the chain right now.

Trace writes from one predecessor​

Start here

Next page if needed

  • Narrow to an exact key if one row becomes the real focus.

Stop when

  • You can answer what this predecessor changed and where.

Switch when

  • The user stops asking about indexed writes and starts asking about the current chain state.

Batch-check several known keys​

Start here

  • Multi Lookup when you already know a fixed set of fully qualified keys.

Next page if needed

Stop when

  • The batch response already answers which of the keys matter.

Switch when

  • You no longer have a fixed key list and need to inspect the contract or predecessor more broadly.

Common mistakes​

  • Starting with broad account or predecessor scans when an exact key is already known.
  • Using KV FastData when the user really wants balances or holdings.
  • Confusing indexed history with exact current chain state.
  • Reusing pagination tokens or changing filters mid-scan.