0
# Blockchain State Access
1

2
The blockchain state access functionality provides comprehensive read access to Ethereum blockchain data including blocks, transactions, accounts, and network state information.
3

4
## Block Operations
5

6
### getBlock
7

8
Retrieves a block by hash or number with optional transaction details.
9

10
```typescript { .api }
11
getBlock(blockHashOrBlockNumber?: BlockNumberOrTag, hydrated?: boolean, returnFormat?: DataFormat): Promise<Block>;
12
```
13

14
**Parameters:**
15
- `blockHashOrBlockNumber`: Block hash (hex string) or block number/tag ("latest", "earliest", "pending", etc.)  
16
- `hydrated`: If true, returns full transaction objects; if false, returns only transaction hashes
17
- `returnFormat`: Output format configuration for numbers and bytes
18

19
**Usage Example:**
20
```typescript
21
// Get latest block with transaction hashes only
22
const latestBlock = await eth.getBlock("latest");
23

24
// Get specific block with full transaction details  
25
const blockWithTxs = await eth.getBlock(15000000, true);
26

27
// Get block by hash
28
const block = await eth.getBlock("0x1234567890abcdef...");
29
```
30

31
### getBlockNumber
32

33
Returns the number of the most recent block.
34

35
```typescript { .api }
36
getBlockNumber(returnFormat?: DataFormat): Promise<Numbers>;
37
```
38

39
**Usage Example:**
40
```typescript
41
const blockNumber = await eth.getBlockNumber();
42
console.log(`Current block: ${blockNumber}`);
43
```
44

45
### getBlockTransactionCount
46

47
Returns the number of transactions in a block.
48

49
```typescript { .api }
50
getBlockTransactionCount(blockHashOrBlockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
51
```
52

53
**Usage Example:**
54
```typescript
55
const txCount = await eth.getBlockTransactionCount("latest");
56
const txCountByHash = await eth.getBlockTransactionCount("0x1234567890abcdef...");
57
```
58

59
### getBlockUncleCount
60

61
Returns the number of uncles in a block.
62

63
```typescript { .api }
64
getBlockUncleCount(blockHashOrBlockNumber?: BlockNumberOrTag, returnFormat?: DataFormat): Promise<Numbers>;
65
```
66

67
### getUncle
68

69
Returns an uncle block by block hash/number and uncle index.
70

71
```typescript { .api }
72
getUncle(blockHashOrBlockNumber?: BlockNumberOrTag, uncleIndex?: Numbers, returnFormat?: DataFormat): Promise<Block>;
73
```
74

75
## Transaction Operations
76

77
### getTransaction
78

79
Retrieves a transaction by its hash.
80

81
```typescript { .api }
82
getTransaction(transactionHash?: HexString32Bytes, returnFormat?: DataFormat): Promise<Transaction>;
83
```
84

85
**Usage Example:**
86
```typescript
87
const tx = await eth.getTransaction("0xabcdef1234567890...");
88
console.log(`From: ${tx.from}, To: ${tx.to}, Value: ${tx.value}`);
89
```
90

91
### getTransactionFromBlock
92

93
Retrieves a transaction from a block by index.
94

95
```typescript { .api }
96
getTransactionFromBlock(blockHashOrBlockNumber?: BlockNumberOrTag, indexNumber?: Numbers, returnFormat?: DataFormat): Promise<Transaction>;
97
```
98

99
**Usage Example:**
100
```typescript
101
// Get first transaction from latest block
102
const firstTx = await eth.getTransactionFromBlock("latest", 0);
103
```
104

105
### getTransactionReceipt
106

107
Retrieves the receipt for a transaction by its hash.
108

109
```typescript { .api }
110
getTransactionReceipt(transactionHash?: HexString32Bytes, returnFormat?: DataFormat): Promise<TransactionReceipt>;
111
```
112

113
**Usage Example:**
114
```typescript
115
const receipt = await eth.getTransactionReceipt("0xabcdef1234567890...");
116
if (receipt.status === '0x1') {
117
  console.log("Transaction successful");
118
} else {
119
  console.log("Transaction failed");
120
}
121
```
122

123
### getPendingTransactions
124

125
Returns all pending transactions.
126

127
```typescript { .api }
128
getPendingTransactions(returnFormat?: DataFormat): Promise<Transaction[]>;
129
```
130

131
## Network State Information
132

133
### getProtocolVersion
134

135
Returns the Ethereum protocol version.
136

137
```typescript { .api }
138
getProtocolVersion(): Promise<string>;
139
```
140

141
### getChainId
142

143
Returns the chain ID of the current network.
144

145
```typescript { .api }
146
getChainId(): Promise<Numbers>;
147
```
148

149
**Usage Example:**
150
```typescript
151
const chainId = await eth.getChainId();
152
// 1 for mainnet, 5 for goerli, etc.
153
```
154

155
### isSyncing
156

157
Checks if the node is currently syncing with the network.
158

159
```typescript { .api }
160
isSyncing(): Promise<SyncingStatusAPI | boolean>;
161
```
162

163
**Returns:**
164
- `false` if not syncing
165
- `SyncingStatusAPI` object with sync progress if syncing
166

167
**Usage Example:**
168
```typescript
169
const syncStatus = await eth.isSyncing();
170
if (syncStatus !== false) {
171
  console.log(`Syncing: ${syncStatus.currentBlock}/${syncStatus.highestBlock}`);
172
}
173
```
174

175
### getCoinbase
176

177
Returns the coinbase address (mining reward recipient).
178

179
```typescript { .api }
180
getCoinbase(): Promise<Address>;
181
```
182

183
### isMining
184

185
Checks if the node is currently mining.
186

187
```typescript { .api }
188
isMining(): Promise<boolean>;
189
```
190

191
### getNodeInfo
192

193
Returns information about the connected node.
194

195
```typescript { .api }
196
getNodeInfo(): Promise<string>;
197
```
198

199
## Core Types
200

201
```typescript { .api }
202
interface Block {
203
  hash?: HexString32Bytes;
204
  parentHash: HexString32Bytes;
205
  sha3Uncles: HexString32Bytes;
206
  miner: Address;
207
  stateRoot: HexString32Bytes;
208
  transactionsRoot: HexString32Bytes;
209
  receiptsRoot: HexString32Bytes;
210
  logsBloom: HexString;
211
  difficulty: Numbers;
212
  number: Numbers;
213
  gasLimit: Numbers;
214
  gasUsed: Numbers;
215
  timestamp: Numbers;
216
  extraData: Bytes;
217
  mixHash: HexString32Bytes;
218
  nonce: HexString8Bytes;
219
  totalDifficulty: Numbers;
220
  size: Numbers;
221
  transactions: HexString32Bytes[] | Transaction[];
222
  uncles: HexString32Bytes[];
223
}
224

225
interface Transaction {
226
  hash?: HexString32Bytes;
227
  nonce: Numbers;
228
  blockHash?: HexString32Bytes;
229
  blockNumber?: Numbers;
230
  transactionIndex?: Numbers;
231
  from: Address;
232
  to?: Address;
233
  value: Numbers;
234
  gasPrice?: Numbers;
235
  maxPriorityFeePerGas?: Numbers;
236
  maxFeePerGas?: Numbers;
237
  gas: Numbers;
238
  input: Bytes;
239
  type?: Numbers;
240
  accessList?: AccessList;
241
  chainId?: Numbers;
242
  v?: Numbers;
243
  r?: HexString32Bytes;
244
  s?: HexString32Bytes;
245
}
246

247
interface TransactionReceipt {
248
  transactionHash: HexString32Bytes;
249
  transactionIndex: Numbers;
250
  blockHash: HexString32Bytes;
251
  blockNumber: Numbers;
252
  from: Address;
253
  to?: Address;
254
  cumulativeGasUsed: Numbers;
255
  gasUsed: Numbers;
256
  contractAddress?: Address;
257
  logs: Log[];
258
  logsBloom: HexString;
259
  status: HexString;
260
  effectiveGasPrice: Numbers;
261
  type: Numbers;
262
}
263

264
interface SyncingStatusAPI {
265
  startingBlock: Numbers;
266
  currentBlock: Numbers;
267
  highestBlock: Numbers;
268
  knownStates?: Numbers;
269
  pulledStates?: Numbers;
270
}
271

272
type BlockNumberOrTag = Numbers | "latest" | "earliest" | "pending" | "safe" | "finalized";
273
type DataFormat = { number: NumberFormat; bytes: BytesFormat };
274
```