From 80f1d1ca18edf7799165c059673e36616292c7e3 Mon Sep 17 00:00:00 2001
From: Sina Mahmoodi <1591639+s1na@users.noreply.github.com>
Date: Thu, 4 May 2023 12:59:40 +0200
Subject: [PATCH] website: note about state in graphql (#27211)

graphql: add note about state
---
 docs/interacting-with-geth/rpc/graphql.md | 26 ++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/interacting-with-geth/rpc/graphql.md b/docs/interacting-with-geth/rpc/graphql.md
index c73961b58b..c61211281a 100644
--- a/docs/interacting-with-geth/rpc/graphql.md
+++ b/docs/interacting-with-geth/rpc/graphql.md
@@ -48,7 +48,7 @@ For example, the code snippet below shows how to obtain the latest block number
 
 ```sh
 ❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '{ "query": "query { block { number } }" }'
-{"data":{"block":{"number":6004069}}}
+{"data":{"block":{"number":"0x5b9d65"}}}
 ```
 
 Alternatively store the JSON-ified query in a file (let's call it `block-num.query`) and do:
@@ -78,3 +78,27 @@ request('http://localhost:8545/graphql', query, { number: '6004067' })
     console.log(err);
   });
 ```
+
+## Accessing state
+
+The schema allows for querying parts of state, i.e. accounts and their storage slots. E.g. it is possible to get the balance of the sender of a tx via:
+
+```graphql
+transaction(hash: "0xdad") {
+    from {
+        balance
+    }
+}
+```
+
+It is important to note however that the balance returned here is **not** the balance at the given transaction, rather it is the latest balance of the sender account, i.e. at the head of the chain. It is possible to query the state of this account at a particular block N via:
+
+```graphql
+transaction(hash: "0xdad") {
+    from(block: 6004067) {
+        balance
+    }
+}
+```
+
+As you can see this effect takes in a block number parameter which instructs geth to return the state of this account from an older block. The node needs to have the state for that block persisted, otherwise this query will result in an error. To see how Geth persists state please see this [page](/docs/developers/evm-tracing#state-availability).