Guide

Light client

Asking a node for a balance is trusting the node. Two calls trade that trust for a Merkle proof that closes against a verified header — without downloading the state.

Before you start

Prerequisites

This applies to any consumer that does not run its own node: wallet, point-of-sale terminal, dashboard.

You will need

eav7-sdk in the project; no wallet is needed, this is a read.
A chain above STATEROOT_HEIGHT — below it there is no root to check against.
Willingness to HANDLE the proof error instead of falling back to the raw answer.

Foundation

Why the double call exists

The difference between the three stances below is the whole difference between trusting and verifying.

Ask: GET /address returns a number. If the node lies, you believe it.
Prove: GET /proof returns the encoded account and the Merkle path. The path is checked locally: a swapped balance does not close against the root.
Refuse: A lying node cannot forge the proof. At most it refuses to serve one — and a refusal is detectable.

Step by step

Trusted root, then balance

Order matters: the root has to come from outside the answer you want to verify.

1
Get the root from a verified header
The method fetches the block, recomputes the hash and checks integrity before returning the stateRoot. A node cannot forge a block whose hash and signatures close.
Rust · eav7-sdk
```
// 1) a raiz vem do HEADER, e o header é verificado antes de ser usado:
//    hash recalculada + assinatura do produtor conferida localmente
let raiz = cliente.raiz_confiavel_do_header("latest")?;
```
2
Prove the balance against that root
The proof is checked locally. If the root the node asserts in /proof differs from the one you brought, the call fails with ProvaInvalida instead of returning a number.
Rust
```
// 2) o saldo chega com a prova de Merkle e é conferido CONTRA essa raiz
let saldo = cliente.saldo_provado("E7A4B2…9F21", Some(&raiz))?;
println!("saldo PROVADO: {saldo} e7");
```

Know what comes back

encodedAccount carries big integers as prefixed text; path is the route to the root. The SDK handles decoding — recovering the wrong tag would reject every valid proof.

bash

curl -s https://eavscan.com/proof/E7A4B2…9F21 -H 'Accept: application/json'

{
  "stateRoot": "e7c41f…",
  "encodedAccount": { "balance": "B12500000", "nonce": 41, … },
  "path": [ { "hash": "a91c…", "right": true }, … ]
}

Rust

// SEM a raiz do header, a prova fecha contra a raiz que o PRÓPRIO nó afirmou:
// pega inconsistência interna, não um nó que minta raiz e saldo de forma coerente.
let saldo = cliente.saldo_provado("E7A4B2…9F21", None)?;

Without the root, the guarantee is weaker

Passing None still detects a node's internal inconsistency, but not a node that lies about root and balance coherently. Use the two-call variant whenever the answer is worth money.

Limits

What the proof does not cover

An account proof proves an account, at a height. It is not a substitute for syncing the chain.

STATEROOT_HEIGHT: 1 200 000Below this height blocks carry no stateRoot and the method refuses rather than inventing a root.
Scope: Balance and nonce of the proved account. History, tokens and logs remain the node's word.
Freshness: The proof holds for the height of the root you brought. To track the head, repeat both calls.

Error	When it happens
`ErroCliente::ProvaInvalida`	The path does not lead to the root, or the node's root differs from the one you required. Treat it as a hostile answer.
`ErroCliente::Resposta`	The proof arrived without stateRoot, encodedAccount or path — a malformed response.
`ErroCliente::Api`	The node answered with an HTTP error; 404 means the account does not exist.

Ready to run

The consulta example

Status, account and proved balance in a single run.

bash

cargo run -p eav7-sdk --example consulta -- \
  https://eavscan.com E7A4B2…9F21

Where to go next

Prerequisites

This applies to any consumer that does not run its own node: wallet, point-of-sale terminal, dashboard.

You will need

eav7-sdk in the project; no wallet is needed, this is a read.
A chain above STATEROOT_HEIGHT — below it there is no root to check against.
Willingness to HANDLE the proof error instead of falling back to the raw answer.

Why the double call exists

The difference between the three stances below is the whole difference between trusting and verifying.

Ask: GET /address returns a number. If the node lies, you believe it.
Prove: GET /proof returns the encoded account and the Merkle path. The path is checked locally: a swapped balance does not close against the root.
Refuse: A lying node cannot forge the proof. At most it refuses to serve one — and a refusal is detectable.

Trusted root, then balance

Order matters: the root has to come from outside the answer you want to verify.

1
Get the root from a verified header
The method fetches the block, recomputes the hash and checks integrity before returning the stateRoot. A node cannot forge a block whose hash and signatures close.
Rust · eav7-sdk
```
// 1) a raiz vem do HEADER, e o header é verificado antes de ser usado:
//    hash recalculada + assinatura do produtor conferida localmente
let raiz = cliente.raiz_confiavel_do_header("latest")?;
```
2
Prove the balance against that root
The proof is checked locally. If the root the node asserts in /proof differs from the one you brought, the call fails with ProvaInvalida instead of returning a number.
Rust
```
// 2) o saldo chega com a prova de Merkle e é conferido CONTRA essa raiz
let saldo = cliente.saldo_provado("E7A4B2…9F21", Some(&raiz))?;
println!("saldo PROVADO: {saldo} e7");
```

Know what comes back

encodedAccount carries big integers as prefixed text; path is the route to the root. The SDK handles decoding — recovering the wrong tag would reject every valid proof.

bash

curl -s https://eavscan.com/proof/E7A4B2…9F21 -H 'Accept: application/json'

{
  "stateRoot": "e7c41f…",
  "encodedAccount": { "balance": "B12500000", "nonce": 41, … },
  "path": [ { "hash": "a91c…", "right": true }, … ]
}

Rust

// SEM a raiz do header, a prova fecha contra a raiz que o PRÓPRIO nó afirmou:
// pega inconsistência interna, não um nó que minta raiz e saldo de forma coerente.
let saldo = cliente.saldo_provado("E7A4B2…9F21", None)?;

Without the root, the guarantee is weaker

Passing None still detects a node's internal inconsistency, but not a node that lies about root and balance coherently. Use the two-call variant whenever the answer is worth money.

What the proof does not cover

An account proof proves an account, at a height. It is not a substitute for syncing the chain.

STATEROOT_HEIGHT: 1 200 000Below this height blocks carry no stateRoot and the method refuses rather than inventing a root.
Scope: Balance and nonce of the proved account. History, tokens and logs remain the node's word.
Freshness: The proof holds for the height of the root you brought. To track the head, repeat both calls.

Error	When it happens
`ErroCliente::ProvaInvalida`	The path does not lead to the root, or the node's root differs from the one you required. Treat it as a hostile answer.
`ErroCliente::Resposta`	The proof arrived without stateRoot, encodedAccount or path — a malformed response.
`ErroCliente::Api`	The node answered with an HTTP error; 404 means the account does not exist.

Prerequisites

Why the double call exists

Trusted root, then balance

Get the root from a verified header

Prove the balance against that root

Know what comes back

What the proof does not cover

The consulta example

Where to go next

Prerequisites

Why the double call exists

Trusted root, then balance

Get the root from a verified header

Prove the balance against that root

Know what comes back

What the proof does not cover

The consulta example

Where to go next